Project Memory

Project Memory stores three types of persistent knowledge in Cortex, enabling agents to learn from past sessions and maintain consistency across conversations.

Memory types

Conventions

Coding patterns, naming rules, and architectural standards observed in the project.

"Use ESM imports, never CommonJS require"
"Tests use vitest with colocated .test.ts files"
"Error messages follow the pattern: [module] description"

Convention categories: naming, architecture, testing, style, security, documentation, tooling, other.

Decisions

Architectural choices with rationale — the "why" behind the codebase.

"Chose TypeBox over Zod for schema validation — better performance, no runtime dependency"
"Using QuickJS WASM sandbox instead of Node VM — true isolation, no fs/net access"

Findings

Discoveries, insights, and debugging patterns learned during work.

"The auth module requires both JWT_SECRET and ADMIN_PASSWORD env vars"
"Race condition in WebSocket reconnect — fixed by adding mutex in connect()"

How knowledge is captured

Automatic extraction

The CompactionExtractor analyzes conversation before context compaction and extracts structured knowledge:

  • agent_end hook: at the end of each agent turn, the conversation is scanned for conventions, decisions, and findings
  • before_compaction hook: before context window compaction, key knowledge is saved to Cortex so it survives the summarization

Extraction patterns identify keywords like "convention", "always use", "decided to", "found that", "the issue was", etc.

Manual capture

  • CLI: mayros kg conventions to list, with future support for adding
  • Tools: cortex_project_memory_store to programmatically add knowledge
  • Tools: cortex_project_memory_query to search stored knowledge

Cross-session recall

At before_prompt_build, the memory-semantic plugin queries Cortex for relevant conventions and findings, then injects them into the agent's context. This means:

  • Conventions learned in session 1 are applied in session 2
  • Debugging findings from last week are available today
  • Architectural decisions are consistently referenced

Configuration

json5
{
  projectMemory: {
    enabled: true,           // Enable/disable project memory
    autoExtract: true,       // Auto-extract on agent_end and before_compaction
    maxConventions: 100,     // Max stored conventions per project
  },
}