Curate Project Memory

Curate Project Memory

Use conversation as the interface. Do not ask the user to run commands or edit configuration manually. Use Codex's normal file tools and request narrowly scoped filesystem permission when needed.

First-run experience

When the user invokes PMC and no project registration exists for the current repository, lead with a concise guided setup instead of describing the architecture:

1. Explain in one sentence: "PMC gives Codex lasting project context in an Obsidian vault you control."
2. Ask whether to create a new vault or connect an existing Obsidian vault. Ask only this one question first.
3. After that choice, ask for or confirm the vault path, infer the current repository, and propose a readable project name.
4. Complete the vault setup and project registration conversationally. Do not require the user to know commands, markers, folder layouts, or configuration formats.
5. Create useful initial notes rather than empty shells whenever the repository can be inspected safely.
6. At completion, state where the vault and project notes live, explain how to open the vault in Obsidian, and offer to scan the repository now.
7. End with these examples: "@PMC remember this", "@PMC what do we already know about authentication?", and "@PMC wrap up this task".

Do not overwhelm a first-time user with advanced features. Introduce context packs, health checks, exports, team review, and the companion only when relevant.

Read references/project-profiles.md when choosing registration defaults.

Read references/local-similarity.md before building or querying the optional machine-local similarity index.

Read references/storage-and-portability.md for setup or project registration. Read references/automatic-orientation.md when the user wants the vault added as a project source or wants future chats to load project notes without a prompt. Read references/durable-note-policy.md before promoting, changing, or removing knowledge. Read references/note-structure.md when creating notes. Read references/context-packs.md when orienting or resuming work. Read references/knowledge-health.md before auditing a vault. Read references/code-traceability.md when relating notes to source files. Read references/branch-awareness.md before promoting knowledge discovered on a branch or worktree. Read references/drift-detection.md before creating or running verification checks. Read references/coverage.md before assessing documentation coverage. Read references/team-collaboration.md before configuring shared-vault ownership or reviews. Read references/exports.md before creating a portable brief or audit artifact. Read references/obsidian-companion.md when installing, configuring, or responding to review actions from the optional Obsidian companion.

Boundaries

• Operate only on local paths that the user selects or places in scope.
• Do not upload, transmit, or add telemetry.
• Do not request or capture complete raw chat transcripts.
• Store an optional concise session summary only when the user asks to wrap up or enables summaries.
• Exclude secrets, credentials, private keys, authentication cookies, and unnecessarily sensitive data.
• Treat the vault as curated knowledge, not a chat archive.
• Never contradict, delete, or supersede durable knowledge silently.
• Do not require Obsidian community plugins.
• If local filesystem access is unavailable, explain that setup requires a local Codex environment; do not pretend files were created.

Set up a vault

Determine whether the user clearly requested a new vault or an existing vault. If ambiguous, ask one short question.

New vault

1. Confirm the path and request permission if necessary.
2. Refuse to repurpose a populated non-Obsidian folder without explicit confirmation.
3. Create the selected folder and an empty .obsidian directory.
4. Create only the minimal shared structure from references/note-structure.md.
5. Create the machine-local configuration described in references/storage-and-portability.md.
6. Report the created paths and explain that the folder can now be opened in Obsidian.

Existing vault

1. Confirm that the folder exists.
2. Treat .obsidian as evidence that it is an Obsidian vault.
3. If .obsidian is absent, explain that it appears to be a Markdown folder and ask before using it.
4. Preserve the existing organisation. Do not move or rename existing content unless asked.
5. Add project-memory notes incrementally and only where useful.

Register a project

1. Infer the repository root from the current workspace when possible.
2. Ask for a project name and vault folder only when they cannot be inferred safely.
3. Create a stable lower-case project ID that does not depend on drive letters.
4. Store the absolute repository path only in machine-local configuration.
5. Store repository-relative code references in durable notes.
6. Create Project Home.md, Project.md, and Current State.md from the bundled templates when missing. Project Home.md is the attractive human-facing front door; Project.md remains the compact compatibility index used by existing workflows. Do not create empty directory forests.
7. Create Inbox/Promotion Inbox.md, Handoff.md, Coverage.md, and the useful Bases dashboards described in references/note-structure.md unless the user opts out.
8. Offer automatic project orientation as an opt-in. If accepted, follow references/automatic-orientation.md and preserve existing repository instructions.
9. Infer or ask for an optional project profile only when it improves initial coverage areas. Do not create empty folders from a profile.

Create the initial project orientation

Trigger on requests such as "create an overview of this codebase", "scan this project", or acceptance of the setup offer.

1. Inspect the repository's primary README, package or build metadata, repository instructions, top-level structure, Git status, and a small number of entry points relevant to understanding the project.
2. Summarize what the project does, how it is organised, how to run or test it, its current state, important constraints, and likely next actions. Distinguish verified facts from inference.
3. Populate Project Home.md, Project.md, and Current State.md; create focused decision, constraint, discovery, procedure, or debugging-lesson notes only when evidence supports them.
4. Link useful notes from Project Home.md and keep it concise enough to scan quickly in Obsidian.
5. Report the evidence inspected and the exact vault files created or updated.

Use the vault as a project source

For a Codex local project, guide the user through the one-time UI action: open Edit project, select Add folder, add the vault, and keep the code repository as the primary folder. Do not claim to have attached a folder through the UI.

Treat the vault as a secondary source folder. Read and edit only relevant notes. Secondary folders do not automatically contribute their own AGENTS.md, skills, or project configuration, so put automatic-orientation guidance in the primary code repository after explicit opt-in.

Enable automatic project orientation

1. Confirm that the user wants relevant durable notes read at the beginning of future tasks for this repository.
2. Copy the managed block from assets/agents-project-memory.md into the primary repository's AGENTS.md; create that file only when necessary.
3. Replace the project ID token and preserve all unrelated instructions.
4. Do not include an absolute vault or repository path in AGENTS.md.
5. On future tasks, load Project.md and Current State.md first, then follow only relevant links.
6. If the vault is unavailable or permission is missing, continue safely and state that project-memory context was not loaded.

Recognize markers

Interpret natural equivalents, not only exact prefixes:

• Remember: -> confirmed durable candidate.
• Decision: -> decision candidate with rationale and consequences.
• Constraint: -> requirement or constraint candidate.
• Reference: -> durable reference candidate.
• Session only: -> do not promote to durable notes.
• Forget: -> propose correction, removal, or supersession and require confirmation.

Treat these natural requests as first-class equivalents:

• @PMC remember this -> summarize the immediately preceding durable point and ask for confirmation when its scope is ambiguous.
• @PMC remember the decision we just made -> create or update a decision after conflict and evidence checks.
• @PMC update the project status -> propose a concise Current State.md update.
• @PMC what do we already know about X? -> build a focused context pack and answer with note links.
• @PMC wrap up this task -> follow the wrap-up workflow.

Markers never bypass secret filtering or conflict checks.

Prompt for knowledge worth keeping

Do not rely on the user to remember a special marker. During ordinary project work, notice information that is likely to matter in a future task, especially:

• an accepted architectural or product decision and its rationale;
• a durable constraint, invariant, convention, or non-obvious requirement;
• a verified discovery that changes how the project should be understood;
• a reusable procedure, workaround, or operational lesson;
• a change that makes an existing durable note stale or incorrect.

At a natural checkpoint, ask one concise question: "This will matter in future tasks. Add it to the project's Obsidian vault?" Include a one-line summary of exactly what would be recorded. Do not interrupt for routine edits, speculative ideas, transient debugging output, or facts already captured. Batch multiple related candidates into one review prompt when practical.

If the user says yes, treat that response as an explicit durable marker and follow the normal conflict, branch, evidence, and secret checks before writing. If the user says no, keep it session-only and do not repeatedly ask about the same candidate. When wrapping up, always include a short separate list titled Worth adding to the project's Obsidian vault or state that no durable candidates were found.