The Vault

The Vault

The vault is a folder of markdown, ~/logos by default. It is the truth. .logos/ holds a SQLite index and embeddings, which are a cache:

rm -rf ~/logos/.logos && logos index     # nothing is lost

Layout

~/logos/
  sessions/<project>/
    _convos/<host-session-id>/<timestamp>-<agent>.md   # checkpoints, by conversation
    _convos/_unattached/<timestamp>-<agent>.md         # checkpoints from the CLI etc.
    uncommitted.md                                     # notes not yet checkpointed
    ledger.md                                          # written by `logos ledger`
  memories/
    <kind>.md                                          # fact, preference, person, …
    <kind>/<id>.md
    log.md                                             # timeline of every change
  activity/                                            # Claude Code activity log (.jsonl)
  usage/                                               # usage counters (.jsonl)
  daily/  people/  projects/  topics/                  # your own notes, if you keep them
  auto.md                                              # what Logos may do on its own
  .logos/                                              # index.db, config — do not sync

Your own notes anywhere in the vault are indexed too. Search, context and the graph use them, and [[wikilinks]] become graph edges.

Vaults from before conversation folders keep checkpoints flat in sessions/<project>/. logos migrate sessions moves them and says how many it moved.

Editing by hand

Anything can be edited. Run logos index afterwards, or turn on logos config auto config index on. logos index --watch keeps the index synced continuously.

Write order

Logos always writes the markdown first and the index second. If it crashes between the two, the cache is stale and the next logos index fixes it. It can't leave the index pointing at something the vault never got. The test suite kills the process mid-write, fills a disk, and races two processes against one vault to hold to this.

Opening it in Obsidian

Open folder as vault and pick ~/logos. Nothing needs converting.

• Obsidian hides dot-folders, so .logos/ never shows. Logos skips them too, so .obsidian/ and .trash/ are never indexed.
• Logos reads [[note]], [[note|text]], [[note#heading]], ![[embed]] and [[note.md]] the way Obsidian resolves them. It doesn't read markdown links [text](note.md).
• A checkpoint's relations frontmatter is a list Obsidian's Properties panel can't edit, so use source mode. Its [[project]] link shows as unresolved; creating that note does no harm.
• In memory files, edit the text before the <!-- logos id=… --> comment and leave the comment alone.

Sharing a vault with a team

The vault is markdown, so git is the sync layer, the history and the conflict resolution.

• logos index adds .logos/ to the vault's .gitignore and tells you the first time it does.
• A teammate's logos memory add becomes a line in memories/<kind>.md and reaches you the way their code does: commit, push, pull.
• After a git pull, the next logos index picks up their checkpoints, notes and memories.
• Logos never runs git for you. No staging, committing or pulling. Sync on your own terms.

If you share a vault, leave --keep-transcripts off. Raw transcripts are not redacted.

Several vaults

Point LOGOS_VAULT at another folder, or run logos setup --vault DIR. Each host's config pins the vault it uses, so always use an absolute path.