Project Brain

Use this skill to operate the bundled ProjectBrain Memory OS.

The bundled implementation is:

• CLI: <skill-dir>\scripts\memory_os.py
• Default memory root: repo-local .\.project-brain
• Rules file: <memory-root>\system\AGENTS.md

What This Skill Does

Treat ProjectBrain as a compiled, local-first memory layer for project work.

Use it to:

• bootstrap the memory tree
• ingest raw lessons, notes, logs, or files
• compile memory so relationships improve over time
• lint the graph for structural drift
• answer questions from grounded project memory
• plan the next durable work from the current memory graph

Do not use it as a chatbot. Use it to maintain a filesystem-backed knowledge layer.

Implicit Capture Policy

You do not need an explicit $project-brain request to update memory.

When working inside a repo, prefer this default behavior:

• read from ProjectBrain whenever project memory is relevant
• write to ProjectBrain only when the outcome is durable and likely to matter again

Automatically capture new memory when the current task yields:

• a reusable fix
• a root cause
• a project-specific gotcha
• a stable best practice
• a decision with rationale
• an experiment and its result
• a workflow improvement that will likely recur

Do not auto-capture:

• casual Q and A
• speculative guesses that are not yet validated
• trivial lookups
• one-off conversational advice
• content with no likely future reuse

If you auto-capture, say so explicitly in the response and list the files that changed.

Core Model

ProjectBrain uses this fixed structure under the resolved memory root:

memory-os/
|-- raw/
|-- sources/
|-- entities/
|-- topics/
|-- decisions/
|-- experiments/
|-- logs/
|-- tasks/
`-- system/

Workflow order is mandatory:

RAW -> SOURCES -> ENTITIES -> TOPICS -> LOGS

Rules that must hold:

• raw/ is immutable after capture
• prefer updating an existing file over creating a new one
• preserve contradictions instead of deleting them
• keep related items linked
• keep markdown human-readable and debuggable
• treat topics/project-memory-overview.md as the high-level synthesis page
• treat tasks/ as the durable planning layer for next work

First Step In Every Session

Before making substantive changes:

1. Resolve the active memory root:
   • nearest repo root + .\.project-brain
   • otherwise current working directory + .\.project-brain
   • override with --root when needed
2. Read <memory-root>\system\AGENTS.md if it exists
3. Inspect the relevant memory files under the active memory root
4. If present, read topics/memory-retrieval-contract.md to learn the repo's preferred memory read order
5. Prefer reading topics/project-memory-overview.md and relevant tasks/ files before adding new memory
6. If the request depends on the current graph state, run lint or query first

Always keep the resolved root explicit in your working notes and final response.

The skill is self-contained. Do not depend on C:\ProjectBrain during normal use.

Commands

Run the bundled script from any working directory.

py -3 C:\Users\niklasb\.codex\skills\project-brain\scripts\memory_os.py bootstrap
py -3 C:\Users\niklasb\.codex\skills\project-brain\scripts\memory_os.py /ingest "Decision: adopt feature flags for safer releases."
py -3 C:\Users\niklasb\.codex\skills\project-brain\scripts\memory_os.py /ingest --file C:\path\to\postmortem.md --label "Release Postmortem"
py -3 C:\Users\niklasb\.codex\skills\project-brain\scripts\memory_os.py /compile
py -3 C:\Users\niklasb\.codex\skills\project-brain\scripts\memory_os.py /lint
py -3 C:\Users\niklasb\.codex\skills\project-brain\scripts\memory_os.py /query "What do we know about release safety?"
py -3 C:\Users\niklasb\.codex\skills\project-brain\scripts\memory_os.py /plan
py -3 C:\Users\niklasb\.codex\skills\project-brain\scripts\memory_os.py /plan "release safety and rollout risk"

By default, the CLI uses .\.project-brain at the current repo root.

If the user wants a different memory root, pass --root <path>.

Example from inside a repo:

py -3 C:\Users\niklasb\.codex\skills\project-brain\scripts\memory_os.py bootstrap

That should initialize:

<repo>\.project-brain\

Shell Command Hygiene

When you emit or run shell commands for ProjectBrain work on Windows:

• Always prefer single-line PowerShell-compatible commands.
• Never split a path argument across lines.
• Quote full paths when they may contain spaces.
• Prefer single-quoted regex patterns when using rg from PowerShell.
• Pass each target path as its own argument instead of relying on shell expansion tricks.

Preferred search shape:

rg -n '(decision|experiment|incident|gotcha|rollback|validation)' .\ .project-brain

If rg is unavailable, blocked, or fails to launch, fall back to PowerShell-native search instead of retrying the same command shape:

Get-ChildItem -Path .\.project-brain -Recurse -File | Select-String -Pattern 'decision|experiment|incident|gotcha|rollback|validation'

Do not assume a wrapped command shown in the UI is safe to copy back into PowerShell unchanged.

Task Workflow

Bootstrap

Use when the memory tree does not exist yet or the user asks to recreate the baseline structure.

1. Run bootstrap
2. Confirm the folder tree exists
3. Inspect seeded examples if they matter to the task

Ingest

Use when the user gives you:

• pasted notes
• postmortems
• architecture docs
• logs
• local files
• lessons learned
• best practices or mistakes worth preserving

Also use implicitly when the current task itself produced a durable lesson that should be preserved.

Behavior:

1. Capture the raw input into raw/
2. Let the CLI write a sources/ summary
3. Update entities/, topics/, decisions/, and experiments/
4. Refresh topics/project-memory-overview.md when the new material changes the project-level picture
5. Let the log capture the action
6. Report the concrete files created or updated

Guardrails:

• Never edit raw/
• Prefer merging into existing entities/topics
• If many related lessons arrive together, cluster them before writing so memory grows by synthesis instead of fragmentation
• If the ingest is broad, run compile afterward
• If the result is not durable enough, skip ingest instead of forcing memory growth

Compile

Use after multiple ingests or when the graph looks fragmented.

Behavior:

1. Normalize document paths from titles
2. Prune generic junk entities
3. Merge exact duplicates
4. Rewrite stale references
5. Strengthen relationships
6. Refresh topics/project-memory-overview.md

Use compile when you need the memory system to become cleaner and more connected, not just larger.

Lint

Use when the user asks for:

• audit
• health check
• contradiction scan
• duplicate detection
• orphan detection
• improvement suggestions

Behavior:

1. Run /lint
2. Prioritize hard problems first
3. Summarize findings with file references
4. If needed, follow with /compile

Query

Use when the user asks a project-memory question.

Behavior:

1. Run /query
2. Read the returned grounded answer
3. If the answer looks too thin, inspect the referenced files and ingest missing context
4. If the answer is durable and likely to matter again, file it back into topics/, decisions/, experiments/, or tasks/

Plan

Use when the user asks:

• what should we do next
• what gaps exist in project knowledge
• what should be remembered as follow-up work
• where the current risks or weak spots are

Behavior:

1. Read topics/project-memory-overview.md
2. Read relevant decisions/, experiments/, tasks/, and recent logs/
3. Identify missing synthesis, repeated failures, weak coverage, or unresolved follow-up work
4. Update an existing task file when the workstream already exists; otherwise create a focused new task file under tasks/
5. Link the task file back to the relevant memory pages
6. Log the planning activity

Guardrails:

• Do not create a parallel planning system outside tasks/
• Prefer a small number of durable workstreams over many throwaway task files
• Planning should reflect compiled memory, not just the last chat turn

How To Respond

When you act on ProjectBrain:

• state the active memory root first
• report the command you ran in plain language
• name the files created or updated
• state whether memory was updated or intentionally skipped
• call out contradictions or low-confidence areas
• suggest the next best operation when useful, usually compile, lint, plan, or another ingest

Preferred phrasing:

• Active memory root: C:\path\to\repo\.project-brain
• Updated under C:\path\to\repo\.project-brain: ...
• Memory update skipped: no durable lesson was produced by this task.

Constraints

• Do not add a database
• Do not add embeddings unless the user explicitly changes the architecture
• Do not bypass the markdown memory system with ad hoc notes elsewhere
• Do not create duplicate concept files when an update would do