claude-memory-architecture — Claude Code rule: setup and details
claude-memory-architecture defines the technical architecture for the claude-memory plugin, detailing hook lifecycles, SQLite database operations, lock handling, and local vector indexing.
no license ★ 276 updated 2026-10-29
.claude/rules/claude-memory-architecture.mdWhat claude-memory-architecture does
This architectural rule sets execution standards for the claude-memory system inside Claude Code. Execution hooks supervise startup routines and shutdown synchronization. On launch, background tasks initialize ~/.claude-memory/, import past transcripts, and update search indices. All records persist in an SQLite database using WAL mode with a 5-second busy timeout.
Runtime scripts must rely entirely on the Python standard library, as external packages like PyYAML are forbidden. Process coordination depends on OS-level flock or msvcrt locks. Using PID files is prohibited because check-then-acquire races cause concurrency conflicts between background jobs.
Text retrieval cascades down through FTS5, FTS4, and LIKE queries. Vector retrieval connects optionally to a local Ollama instance generating 256-dimension embeddings. An integrated adapter also ingests Codex desktop sessions into the shared message tables.
What it helps with
- organize lifecycle hook sequencing inside Claude Code
- coordinate concurrent background jobs with OS file locks
- maintain unified session history in an SQLite database
- combine full-text indexing with vector search across past sessions
Example prompts for the agent
- Review the hook execution pipeline configured for session startup in claude-memory
- Check how SQLite migrations and OS locks must be implemented in the plugin scripts
- Explain the background sync mechanism triggered on session termination
How to install claude-memory-architecture
Manually: put the files in place
.claude/rules/claude-memory-architecture.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/claude-memory-architecture.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/claude-memory-architecture.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/claude-memory-architecture.mdManually: put the files in place
.clinerules/claude-memory-architecture.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about claude-memory-architecture
How to install claude-memory-architecture in Claude Code?
Add the rule file to your project at .claude/rules/claude-memory-architecture.md.
What does the claude-memory-architecture rule govern?
It outlines internal specifications for claude-memory, covering SQLite schema design, migration safety, hook timing, and search mechanics.
Why does the architecture forbid third-party packages?
Runtime plugin code is intentionally restricted to the Python standard library to ensure portability across operating systems.