dimensionalOS / dimensionalOS/dimos

Restructure `dimos/` files

Open
#2,878 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

this week
Dominant language
Python
Stars
4.5k
Forks
808
Avg merge
3d 5h
Merged PRs (30d)
233

Description

The project has grown in some random ways and it would be helpful to logically reorder some of the directories in dimos/.

This will be quite disruptive, but I think necessary (and better now than later).

First PR:

  • learning to imitation (it's about imitation learning so we should probably narrow it down)
  • core/tests to core/demos
  • agents/{testing.py,agent_test_runner.py,vlm_stream_tester.py} to agents/testing/

Some proposals (all relative to /dimos/):

  • memory2 to memory
  • robot/cli and utils/cli to cli
  • all the blueprint specifications to blueprints including all_blueprints.py and related
  • mapping/utils/cli to mapping/clior cli
  • spec/utils.pyto core/spec.py (this contains the is_spec stuff used in blueprints/modules)
  • navigation/visual/query.py and navigation/bbox_navigation.py to agent/skills
  • models/qwen to models/vl/qwen (like the others)
  • perception/experimental/temporal_memory to experimental/temporal_memory
  • perception/object_tracker.py (and \_2d/\_3d) to perception/tracking
  • perception/{spatial_perception.py,spatial_vector_db.py,visual_memory.py} into perception/spatial_memory/
  • delete msgs/sensor_msgs/image_impls/AbstractImage.py (can't, it's used by data/unitree_go2_bigoffice/video)
  • skills folded into the rest of the skills in agent/skills
  • agents/system_prompt.py to robot/unitree/go2/system_prompt.py
  • utils/docs/doclinks.py to cli/docklinks.py

Other:

  • I think we should break up protocol. You wouldn't have a directory called classes or functions. Things should be grouped by their area, not what they are. It's especially not a good idea since protocol doesnt just contain Protocols, but also implementations in protocol/pubsub/impl and benchmarks
  • Pubsub stuff should be moved into core/pubsub(out of protocol)
  • Move transport stuff to core/transport(e.g. core/transport.py, core/transport_factory.py

Please expand, if you have suggestions.

  • If you disagree with something
    • Please add a sub point like this. If you feel very strongly that something is bad, please cross off the item

Ideally, if project is structured really well, there wouldn't be so many cross project imports. This is our current project (dirs below 10000 lines are collapsed)

2026-07-12_02-02.png


Synced from DIM-1181 by paul.nechifor

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the proposed moves under dimos/, especially protocol, pubsub, transport, and agent/skills, then trace the cross-project imports affected by each. The work is done when the directory structure has an agreed design and the affected imports and references are updated consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
developer-experience, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.