Project Memory

Rootloom Memory

Keep a small, local, reviewable memory in .project-memory/. This Skill is shipped by the separately installed rootloom-memory plugin, never by Rootloom Core. It is an experimental engineering aid, not an authority, prerequisite, or automatic activity log.

Rules

• Query memory at task intake by the paths and intent actually in scope; do not inject the whole project history when only a few entries are relevant.
• Treat every result as a lead. Verify it against current source, tests, schemas, manifests, CI, and runtime evidence.
• Record only durable facts or explicitly labeled hypotheses that will change a future engineering decision. Do not copy task transcripts, model reasoning, raw logs, credentials, or sensitive payloads.
• Attach compact evidence references when practical. Prefer current repository paths, test names, issue/trace references, or accepted decision records over pasted evidence.
• Never initialize, record, resolve, supersede, or refresh memory silently. Every write is an explicit command followed by diff review.
• Keep accepted architecture and contract decisions in the repository's durable

decision-record convention; decisions.json is only a relevant index. Maintain stable ownership and dependency rules in architecture.md with current evidence links.

Initialize

python3 /scripts/project_memory.py --repo /path/to/repo init

This creates the compatible rootloom-project-memory-v1 files only when absent:

.project-memory/
├── README.md
├── architecture.md
├── known-risks.json
├── decisions.json
└── failures.json

Retrieve relevant context

Use repeatable paths plus the task intent. Context is read-only, bounded, and excludes expired, resolved, or superseded entries by default:

python3 /scripts/project_memory.py --repo /path/to/repo context \
  --path src/relay.py \
  --query 'fix reconnect ordering' \
  --limit 8

The result keeps architecture, failures, risks, and decisions as direct fields for compatibility. selection explains the query/truncation, while stale names matching historical entries that must not silently influence the current decision. Use --include-stale only when investigating history.

Record verified lessons

Failure lesson:

python3 /scripts/project_memory.py --repo /path/to/repo record-failure \
  --summary 'Relay reconnect failed' \
  --root-cause 'Connection state transition race' \
  --fix 'Serialize transitions in the connection state machine' \
  --path src/relay.py \
  --evidence tests/test_relay.py::test_reconnect

Known risk:

python3 /scripts/project_memory.py --repo /path/to/repo record-risk \
  --summary 'Relay reconnect ordering is fragile' \
  --mitigation 'Exercise repeated and cancelled transitions' \
  --path src/relay.py \
  --evidence docs/decisions/relay-lifecycle.md \
  --expires 2027-01-01

Decision index:

python3 /scripts/project_memory.py --repo /path/to/repo record-decision \
  --summary 'All worker calls cross the relay boundary' \
  --record docs/decisions/relay-boundary.md \
  --path src/relay.py

New entries receive a deterministic ID, active status, evidence/path metadata, and optional expiry. Repeating the exact record reports deduplicated: true and does not grow the collection.

Resolve or supersede

Lifecycle changes are explicit and preserve history:

python3 /scripts/project_memory.py --repo /path/to/repo set-status \
  --kind risks \
  --id risk-0123456789abcdef \
  --status resolved

Use --status superseded --superseded-by when another entry replaces the old one. Inspect the resulting JSON diff before accepting it.

Compatibility and limits

• Existing v1 envelopes and legacy entries without ID, status, paths, evidence, or expiry remain readable and are never rewritten by context.
• Collections are bounded to 1 MiB and 1,000 entries; architecture context is bounded to 64 KiB; query output defaults to 20 entries per kind and accepts 1–100.
• Memory paths must be normalized repository-relative paths. Symlinked memory directories/files are refused or ignored to keep repository memory inside its owning boundary.
• No database, vector index, embeddings, daemon, Hook write, or network service is involved.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qingye-lab
• Source: qingye-lab/rootloom
• License: MIT
• Homepage: https://qingye-lab.github.io/rootloom/

Install and usage instructions live in the source repository linked above.