akashic-codebase-map

name	akashic-codebase-map
description	Complete map of the Akashic Context codebase — key files, types, conventions, and current implementation state. Preload into agents working on this project.
user-invocable	false

Akashic Context — Codebase Map

Project Structure

packages/
├── core/src/
│   ├── types.ts              <- Core interfaces: Message, MemoryConfig, MemoryChunk, Session
│   ├── index.ts              <- Main exports
│   ├── memory/
│   │   ├── manager.ts        <- MemoryManager class (orchestrates everything)
│   │   ├── storage.ts        <- MemoryStorage class (SQLite + FTS5)
│   │   ├── chunking.ts       <- chunkMarkdown() (~400 tokens, 80 overlap)
│   │   ├── hybrid.ts         <- mergeHybridResults() (70% vec + 30% keyword)
│   │   ├── manager.test.ts   <- Unit tests for MemoryManager
│   │   └── providers/
│   │       └── openai.ts     <- createOpenAIEmbeddingProvider()
│   └── utils/
│       ├── hash.ts           <- hashText(content): string
│       └── files.ts          <- listMemoryFiles(), exists(), ensureDir()
│
└── mcp-server/src/
    ├── index.ts              <- MemoryMcpServer class (4 MCP tools)
    ├── cli.ts                <- CLI entry point (env vars + args)
    └── index.test.ts         <- Unit tests for MCP server

Key Classes and Interfaces

MemoryManagerConfig (manager.ts)

interface MemoryManagerConfig {
  dataDir: string;       // Where DBs are stored
  userId: string;        // User identifier
  sessionId?: string;    // Optional session scope
  workspaceDir: string;  // Where MEMORY.md + memory/*.md live
  memory: MemoryConfig;
  vectorExtensionPath?: string;
}

StorageConfig (storage.ts)

interface StorageConfig {
  dataDir: string;
  userId: string;
  sessionId?: string;
}
// Current DB path: {dataDir}/memory_{userId}.db
// Sprint 0 target: {dataDir}/users/{userId}/memory.db

MemoryStorage constructor (storage.ts:85-92)

constructor(config: StorageConfig) {
  const sessionPart = config.sessionId ? `_${config.sessionId}` : "";
  const dbName = `memory_${config.userId}${sessionPart}.db`;
  this.dbPath = path.join(ensureDir(config.dataDir), dbName);
  // ...
}

MemoryMcpServer (mcp-server/index.ts)

• 4 tools: memory_search, memory_get, memory_store, memory_delete
• Currently hardcodes userId: "mcp-user" in constructor (line ~51)
• Zod schemas validate all input params
• Error responses use { content: [{ type: "text", text: "Error: ..." }], isError: true }

Current State (Sprint 1 starts here)

Sprint 0 ✅ COMPLETE (2026-03-06)

Component	State
userId in all 4 MCP tools	✅ optional, default "default"
Per-user workspace users/{userId}/	✅ implemented
Per-user DB users/{userId}/memory.db	✅ implemented
working-memory.ts + context.json	✅ implemented
memory_context MCP tool	✅ implemented
Manager pool getOrCreateManager(userId)	✅ implemented
Isolation tests	✅ 12 tests passing
memory_store path validation	✅ must be memory/ or MEMORY.md
minScore default	✅ changed 0.35 → 0.15

Sprint 1 🎯 IN PROGRESS

Component	State
cosineSimilarity() in storage.ts	❌ does not exist
searchVectorInProcess() in storage.ts	❌ does not exist
Hybrid merge using real vector results	❌ falls back to keyword only
memory_add MCP tool	❌ does not exist
extractionModel config	❌ does not exist
OpenAI chat client in MCP server	❓ check if embedding provider exposes it

MCP Server Current Tools (5 tools)

memory_search  — BM25 keyword (vector fallback ready, not yet wired)
memory_get     — read file by path
memory_store   — write file (must be memory/ or MEMORY.md)
memory_delete  — delete file (protects MEMORY.md)
memory_context — get/set context.json scratchpad

listMemoryFiles() constraint (CRITICAL)

packages/core/src/utils/files.ts ONLY scans:

• {workspaceDir}/MEMORY.md
• {workspaceDir}/memory/*.md

Files at any other location are NOT indexed. memory_store enforces this with a validation error.

Conventions

• TypeScript ESM strict — always use .js extensions on imports
• No any — use explicit types
• Files under ~500 LOC
• Tests colocated — *.test.ts next to source
• Utilities available: ensureDir(dir), exists(path), hashText(content), listMemoryFiles(dir)
• Test command: pnpm test -- --run
• Build command: pnpm build
• 47+ tests currently passing — must stay green

Existing Tests Location

• packages/core/src/memory/manager.test.ts — MemoryManager unit tests
• packages/mcp-server/src/index.test.ts — MCP handler unit tests
• packages/mcp-server/src/integration.test.ts — End-to-end integration (15 tests)
• packages/mcp-server/src/isolation.test.ts — Multi-user isolation (12 tests)