Give Codex project memory that survives individual chats—curated in your local Obsidian vault.
Codex tasks normally start with an isolated context. Important decisions, user corrections, design rationale, and unresolved issues can therefore disappear between conversations. Obsidian Project Memory turns that knowledge into maintained project cognition: it loads only relevant context before substantive work and distills durable learning afterward. It is not a raw chat archive.
- Start with context. Codex sees the project's current state, active decisions, and relevant constraints before planning or coding.
- Keep memory useful. Notes are organized by project and stable topic, with size budgets and superseded decisions removed from the default loading path.
- Reuse what should be global. Cross-project rules can be promoted to global knowledge; project-specific decisions stay with their project.
- Keep your workflow. Requirement execution documents remain the implementation contract in the repository. The memory layer supplies context while you discuss, write, and execute them.
- Stay local. The plugin works directly with local files. Obsidian does not need to be running.
- Codex desktop or Codex CLI
- macOS or Windows
- Obsidian with at least one local vault
codex plugin marketplace add sherlockmen/obsidian-project-memory
codex plugin add obsidian-project-memory@sherlockmenImportant
Start a new Codex task after installation so Codex can discover the installed skills.
Open the repository in Codex and explicitly invoke:
$obsidian-project-memory:project-memory-setup
The setup flow asks you to confirm the vault, memory language, managed subdirectory, Git mode, and stable project ID. It previews all writes, then separately previews the managed AGENTS.md block before changing the repository.
After setup, simply discuss a requirement, ask for a plan, implement a feature, debug a problem, or request a review. You do not need to invoke the memory skill beside every prompt. The confirmed AGENTS.md block makes memory loading and distillation part of substantive project work.
flowchart LR
A["You start substantive project work"] --> B["AGENTS.md activates project-memory"]
B --> C["Load only relevant Obsidian context"]
C --> D["Plan, discuss, implement, debug, or review"]
D --> E["Extract durable learning and corrections"]
E --> F["Update project or global memory after confirmation"]
The plugin provides two skills with deliberately separate responsibilities:
| Skill | Invocation | Responsibility |
|---|---|---|
project-memory-setup |
Explicit | Connect, repair, migrate, or disconnect a project. It handles vault selection, local mapping, initial notes, and the managed AGENTS.md block. |
project-memory |
Automatic after setup | Load relevant memory, maintain an isolated active-task note, and distill durable context before the task finishes or pauses. |
This separation means planning tools such as grill-with-docs do not need to depend on or know about this plugin. Project memory is already available while you discuss and produce an execution document.
| Information | Source of truth |
|---|---|
| Durable project cognition, rationale, corrections, reusable patterns, and future-relevant unresolved issues | Obsidian project memory |
| Rules that genuinely apply across projects | Obsidian global memory |
| The current requirement's path, scope, and technical implementation plan | Repository requirement execution document |
| Current implementation facts | Code, configuration, schema, migrations, and tests; memory stores only repository-relative pointers and verification dates |
| Absolute repository and vault paths | Local Codex registry only |
Routine progress, temporary reasoning, and successful task history are not kept forever. Sensitive values are never valid memory content.
Setup creates only the minimal structure. Topic, decision, active-task, and unresolved-item directories appear lazily when real content exists.
Project Memory/
├── .project-memory/config.json
├── Global/
│ └── Project Registry.md
└── Projects/
└── <project-id>/
├── Project Home.md
├── Project Status.md
└── ...created only when needed
The Chinese layout uses 项目记忆/全局/项目/项目首页/项目状态. Notes use wikilinks, small metadata blocks, current-state summaries, and repository-relative fact pointers. Replaced decisions remain available as history but leave the default loading path.
- Fully local operation, with no telemetry and no active network access at runtime.
- Only the user-confirmed managed subdirectory is created, scanned, and modified.
- Notes outside that boundary are read only when explicitly linked and are never modified by default.
- Credentials, secrets, tokens, cookies, private keys, environment values, and raw production payloads are prohibited.
- Absolute paths exist only in the local registry, never in repository files or visible vault notes.
- Important decisions, global promotions, deletions, and semantic conflict resolutions require user confirmation.
- Concurrent tasks use active-task isolation, content hashes, and optimistic concurrency checks.
Setup supports three vault modes:
existing: use an existing local Git work tree;initialize: initialize a local repository after showing the exact target and receiving confirmation;none: continue after a recovery warning and create backups before migrations.
The plugin never configures a remote and never runs fetch, pull, or push.
| Environment | Version 0.1 |
|---|---|
| macOS | Supported |
| Windows | Supported |
| Codex desktop | Supported |
| Codex CLI | Supported |
| Linux / WSL | Not yet supported |
| Codex IDE extension | Not yet supported |
| ChatGPT web reading a local vault | Not supported |
| Obsidian application plugin | Not included or required |
Plugin versions and vault schema versions are independent. If the installed plugin cannot safely understand a vault schema, the vault becomes read-only. A migration must show a preview, receive explicit confirmation, and create a recovery point before changing notes.
To update the plugin, use your normal Codex plugin update flow and start a new task afterward. Uninstalling the plugin leaves the Obsidian notes and managed AGENTS.md block in place so no project knowledge is silently deleted.
| Symptom | Action |
|---|---|
| No vault is discovered | Provide the vault path manually and confirm it. |
| Project memory is unavailable | Invoke project-memory-setup to repair the local mapping. |
| The schema is incompatible | Update the plugin or use setup to preview a supported migration. |
The managed AGENTS.md block conflicts |
Resolve the existing root content manually; setup will not overwrite a conflict. |
| A write is rejected as sensitive | Replace the value with a safe abstraction or repository-relative pointer. |
The repository contains the marketplace manifest, the plugin package, platform adapters, and cross-platform contract tests.
python3 tests/validate-package.py
bash tests/test-macos.shWindows behavior is covered by tests/Test-Windows.ps1 in GitHub Actions. Contributions should preserve local-first operation, explicit confirmation boundaries, macOS/Windows parity, and idempotent setup behavior.
Issues and pull requests are welcome in the GitHub repository.