feat: add core project memory package

[johnnyeric]

Context

Add durable, project-scoped memory so Kilo can retain useful facts, decisions, constraints, commands, corrections, and recent session context across conversations. The core is opt-in, local-only, and designed to save durable information rather than transcripts or unsafe model output.

Memory is stored outside the repository under ~/.kilo/memory/<project-name>-<hash>/, keeping the checkout clean while giving Git worktrees a stable shared project identity.

Implementation

The new @kilocode/kilo-memory package provides storage, capture, indexing, and recall primitives without coupling them to a product surface. Its source layout separates durable project facts (project.md), environment notes (environment.md), corrections (corrections.md), compact startup context (index.kmem), session digests, and audit records.

Writes are atomic and serialized with ownership-aware filesystem locks; destructive purge requires a valid memory manifest; source and session changes invalidate the generated index. Capture output is schema-validated, size-limited, and redacted before persistence. Recall uses compact typed records and session digests under explicit byte/token budgets.

Memory output is context, not instruction: current user messages, repository files, tool output, and AGENTS.md remain authoritative when they conflict with saved memory. The package also includes corrupt-state recovery, deterministic command parsing, and regression coverage for deletion safety, concurrent updates, redaction, qualified forget, session replacement, and stale indexes.

Screenshots / Video

N/A — package-only change with no visual surface.

How to Test

Manual/local verification

Executed by the coding agent:

• bun run typecheck from packages/kilo-memory
• bun run build from packages/kilo-memory
• bun test from packages/kilo-memory — 69 tests passed
• Linux index-expiry regression rerun 50 times — 50 passed
• bun run test:ci from packages/kilo-memory
• bun turbo test:ci --filter=@kilocode/kilo-memory from the repository root
• bun run lint from the repository root — 0 errors
• Pre-push bun turbo typecheck — 18 tasks passed

Reviewer test steps

1. Run bun run typecheck && bun run build && bun test from packages/kilo-memory.
2. Review the purge regression to confirm an unrelated directory is preserved and rejected.
3. Review qualified-forget and same-key/different-section regressions to confirm only the selected record changes.
4. Review session replacement, credential redaction, unsupported-state recovery, and deleted-source index invalidation regressions.

Blocked checks and substitute verification

• None. All relevant package, CI task, build, typecheck, and lint checks completed.

Checklist

• Issue linked above, or exception explained
• Tests/verification described
• Screenshots/video included for visual changes, or marked N/A
• Changeset considered for user-facing changes
• I personally reviewed the diff and can explain the changes, including any AI-assisted work.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e6978050dc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

All five previously-flagged findings were addressed in the latest commits:

• capture/redact.ts — URI credential handling rewritten to a parser-primary (new URL) approach with a raw-segment fallback; new tests cover well-formed, malformed, and false-positive cases.
• recall/budget.ts (moved from indexer.ts) — truncation hint now references the supported mode=typed instead of the nonexistent mode=catalog.
• capture/diff.ts (moved from capture.ts) — durable file regex now matches nested docs/..., .kilo/..., and README.*; tests confirm the new cases.
• capture/ops.ts — apply() split into clear load / plan (pure) / commit (IO) phases (planOps, planAdd, planRemove, readDocs, writeDocs, persist).
• storage/sessions.ts — serialization split into content() / draft() / parse(); filesystem access into list() / drop().

The broader extraction into text.ts, markdown.ts, reject.ts, index-format.ts, outcome.ts, parse.ts, plan.ts, digest-text.ts, and memory-notice.ts is clean and improves testability without introducing regressions or new concerns.

Files Reviewed (incremental: 24 files)

• packages/kilo-memory/src/capture/capture.ts - resolved (durable regex moved out)
• packages/kilo-memory/src/capture/diff.ts - resolved (regex improved)
• packages/kilo-memory/src/capture/digest-text.ts - no issues
• packages/kilo-memory/src/capture/digest.ts - no issues
• packages/kilo-memory/src/capture/ops.ts - resolved (apply split into load/plan/commit)
• packages/kilo-memory/src/capture/outcome.ts - no issues
• packages/kilo-memory/src/capture/parse.ts - no issues
• packages/kilo-memory/src/capture/plan.ts - no issues
• packages/kilo-memory/src/capture/redact.ts - resolved (parser-primary redaction + tests)
• packages/kilo-memory/src/capture/reject.ts - no issues
• packages/kilo-memory/src/memory-notice.ts - no issues
• packages/kilo-memory/src/memory.ts - no issues
• packages/kilo-memory/src/recall/budget.ts - resolved (catalog→typed)
• packages/kilo-memory/src/recall/index-format.ts - no issues
• packages/kilo-memory/src/recall/indexer.ts - resolved (facade slimmed)
• packages/kilo-memory/src/recall/shared.ts - no issues
• packages/kilo-memory/src/storage/markdown.ts - no issues
• packages/kilo-memory/src/storage/sessions.ts - resolved (serialization split)
• packages/kilo-memory/src/storage/sources.ts - no issues
• packages/kilo-memory/src/storage/state.ts - no issues
• packages/kilo-memory/src/text.ts - no issues
• packages/kilo-memory/test/capture.test.ts - no issues
• packages/kilo-memory/test/markdown.test.ts - no issues
• packages/kilo-memory/test/text.test.ts - no issues

Previous Review Summaries (3 snapshots, latest commit e7e9efe)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit e7e9efe)

Status: No Issues Found | Recommendation: Merge

All five previously-flagged findings were addressed in the latest commits:

• capture/redact.ts — URI credential handling rewritten to a parser-primary (new URL) approach with a raw-segment fallback; new tests cover well-formed, malformed, and false-positive cases.
• recall/budget.ts (moved from indexer.ts) — truncation hint now references the supported mode=typed instead of the nonexistent mode=catalog.
• capture/diff.ts (moved from capture.ts) — durable file regex now matches nested docs/..., .kilo/..., and README.*; tests confirm the new cases.
• capture/ops.ts — apply() split into clear load / plan (pure) / commit (IO) phases (planOps, planAdd, planRemove, readDocs, writeDocs, persist).
• storage/sessions.ts — serialization split into content() / draft() / parse(); filesystem access into list() / drop().

The broader extraction into text.ts, markdown.ts, reject.ts, index-format.ts, outcome.ts, parse.ts, plan.ts, digest-text.ts, and memory-notice.ts is clean and improves testability without introducing regressions or new concerns.

Files Reviewed (incremental: 24 files)

• packages/kilo-memory/src/capture/capture.ts - resolved (durable regex moved out)
• packages/kilo-memory/src/capture/diff.ts - resolved (regex improved)
• packages/kilo-memory/src/capture/digest-text.ts - no issues
• packages/kilo-memory/src/capture/digest.ts - no issues
• packages/kilo-memory/src/capture/ops.ts - resolved (apply split into load/plan/commit)
• packages/kilo-memory/src/capture/outcome.ts - no issues
• packages/kilo-memory/src/capture/parse.ts - no issues
• packages/kilo-memory/src/capture/plan.ts - no issues
• packages/kilo-memory/src/capture/redact.ts - resolved (parser-primary redaction + tests)
• packages/kilo-memory/src/capture/reject.ts - no issues
• packages/kilo-memory/src/memory-notice.ts - no issues
• packages/kilo-memory/src/memory.ts - no issues
• packages/kilo-memory/src/recall/budget.ts - resolved (catalog→typed)
• packages/kilo-memory/src/recall/index-format.ts - no issues
• packages/kilo-memory/src/recall/indexer.ts - resolved (facade slimmed)
• packages/kilo-memory/src/recall/shared.ts - no issues
• packages/kilo-memory/src/storage/markdown.ts - no issues
• packages/kilo-memory/src/storage/sessions.ts - resolved (serialization split)
• packages/kilo-memory/src/storage/sources.ts - no issues
• packages/kilo-memory/src/storage/state.ts - no issues
• packages/kilo-memory/src/text.ts - no issues
• packages/kilo-memory/test/capture.test.ts - no issues
• packages/kilo-memory/test/markdown.test.ts - no issues
• packages/kilo-memory/test/text.test.ts - no issues

Previous review (commit 7194bf7)

Status: 5 Issues Found | Recommendation: Address before merge (no new issues since last review)

Overview

Severity	Count
CRITICAL	0
WARNING	5
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/kilo-memory/src/capture/redact.ts	27	URI credential regex concern — note: capture.test.ts now includes a test for postgres:// URI redaction (line 319-338), partially addressing the "no tests" concern
packages/kilo-memory/src/recall/indexer.ts	164	Truncation hint references mode=catalog which is not a supported recall mode (Mode is search | typed | digest) — flagged by @chatgpt-codex-connector
packages/kilo-memory/src/capture/capture.ts	171	durable regex uses docs?\/ with $ anchor, failing to match nested docs (e.g. docs/setup.md) or .kilo/ subdirectory files — flagged by @chatgpt-codex-connector
packages/kilo-memory/src/capture/ops.ts	270	apply() mixes validation, deduplication, domain mutation, Markdown editing, filesystem writes, and inventory in one large function — flagged by @chatgpt-codex-connector
packages/kilo-memory/src/storage/sessions.ts	70	Serialization, filesystem access, and replacement logic could be split for better testability — flagged by @chatgpt-codex-connector

Files Reviewed (35 files)

• .changeset/kilo-memory-core.md - No issues
• bun.lock - No issues
• packages/kilo-memory/package.json - No issues
• packages/kilo-memory/src/index.ts - No issues
• packages/kilo-memory/src/commands.ts - No issues
• packages/kilo-memory/src/memory.ts - No issues
• packages/kilo-memory/src/schema.ts - No issues
• packages/kilo-memory/src/slug.ts - No issues
• packages/kilo-memory/src/capture/capture.ts - 1 issue (durable regex)
• packages/kilo-memory/src/capture/digest.ts - No issues
• packages/kilo-memory/src/capture/ops.ts - 1 issue (apply cohesion)
• packages/kilo-memory/src/capture/redact.ts - 1 issue (URI regex tests)
• packages/kilo-memory/src/recall/indexer.ts - 1 issue (catalog mode)
• packages/kilo-memory/src/recall/recall.ts - No issues
• packages/kilo-memory/src/recall/shared.ts - No issues
• packages/kilo-memory/src/recall/token.ts - No issues
• packages/kilo-memory/src/recall/topics.ts - No issues
• packages/kilo-memory/src/storage/audit.ts - No issues
• packages/kilo-memory/src/storage/fs.ts - No issues
• packages/kilo-memory/src/storage/paths.ts - No issues
• packages/kilo-memory/src/storage/sessions.ts - 1 issue (serialization split)
• packages/kilo-memory/src/storage/sources.ts - No issues
• packages/kilo-memory/src/storage/state.ts - No issues
• packages/kilo-memory/src/storage/store.ts - No issues
• packages/kilo-memory/test/capture.test.ts - No issues
• packages/kilo-memory/test/commands.test.ts - No issues
• packages/kilo-memory/test/core.test.ts - No issues
• packages/kilo-memory/test/memory.test.ts - No issues
• packages/kilo-memory/test/recall-fixtures.test.ts - No issues
• packages/kilo-memory/test/command-cases.json - No issues
• packages/kilo-memory/tsconfig.json - No issues
• packages/kilo-memory/src/prompts/session-digest.txt - No issues
• packages/kilo-memory/src/prompts/typed-consolidation.txt - No issues
• packages/kilo-memory/src/prompts/txt.d.ts - No issues

Fix these issues in Kilo Cloud

Previous review (commit 23b4086)

Status: 3 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	3
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/kilo-memory/src/capture/redact.ts	27	URI credential regex has no dedicated unit tests — flagged by @marius-kilocode
packages/kilo-memory/src/recall/indexer.ts	164	Truncation hint references mode=catalog which is not a supported recall mode — flagged by @chatgpt-codex-connector
packages/kilo-memory/src/capture/capture.ts	171	durable regex fails to match nested docs (e.g. docs/setup.md) or .kilo/ subdirectory files because of $ anchor — flagged by @chatgpt-codex-connector

Files Reviewed (14 files)

• packages/kilo-memory/src/capture/capture.ts - 1 issue (durable regex)
• packages/kilo-memory/src/capture/ops.ts - No issues
• packages/kilo-memory/src/capture/redact.ts - 1 issue (untested URI regex)
• packages/kilo-memory/src/capture/digest.ts - No issues
• packages/kilo-memory/src/memory.ts - No issues
• packages/kilo-memory/src/recall/indexer.ts - 1 issue (catalog mode hint)
• packages/kilo-memory/src/recall/recall.ts - No issues
• packages/kilo-memory/src/recall/shared.ts - No issues
• packages/kilo-memory/src/schema.ts - No issues
• packages/kilo-memory/src/storage/audit.ts - No issues
• packages/kilo-memory/src/storage/fs.ts - No issues
• packages/kilo-memory/src/storage/paths.ts - No issues
• packages/kilo-memory/src/storage/sessions.ts - No issues
• packages/kilo-memory/src/storage/state.ts - No issues
• packages/kilo-memory/src/storage/sources.ts - No issues

Fix these issues in Kilo Cloud

---

_{Reviewed by gpt-5.4-20260305 · 146,104 tokens}

_{Review guidance: REVIEW.md from base branch main}

[marius-kilocode]

A non-overengineered architecture improvement (that would make maintenance much easier) could split serialization, file system access and storage modules from the domain logic.