# claude-memory-architecture

claude-memory-architecture defines the technical architecture for the claude-memory plugin, detailing hook lifecycles, SQLite database operations, lock handling, and local vector indexing.

- rule · `type=rule` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline · ★ 276 repo stars
- Author: gupsammy
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/gupsammy/Claudest/tree/HEAD/.claude/rules/claude-memory-architecture.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/rules/claude-memory-architecture

## What it 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.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/rules/claude-memory-architecture.md` — The paths frontmatter field limits the files

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### Cursor

**Manually: put the files in place**
- File: `.cursor/rules/claude-memory-architecture.mdc` — Frontmatter: description, globs, alwaysApply

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/claude-memory-architecture.instructions.md` — The applyTo field sets which files it applies to

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/claude-memory-architecture.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/claude-memory-architecture.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/gupsammy/Claudest/tree/HEAD/.claude/rules/claude-memory-architecture.md

## When to use it
- 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
- 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

## Similar
- [Titen Memory](https://affpapa.org/en/nevibecode/mcp/titen-memory.md) — MCP server · ★ 19 repo stars
- [Local Memory](https://affpapa.org/en/nevibecode/mcp/local-memory.md) — MCP server · ★ 15 repo stars
- [claudex](https://affpapa.org/en/nevibecode/mcp/claudex.md) — MCP server · ★ 97 repo stars
- [recall](https://affpapa.org/en/nevibecode/plugins/recall.md) — plugin · ★ 23 repo stars
- [Kagura Memory Cloud](https://affpapa.org/en/nevibecode/mcp/kagura-memory-cloud.md) — MCP server · ★ 14 repo stars
- [Provena Agent Memory](https://affpapa.org/en/nevibecode/mcp/provena-agent-memory.md) — MCP server · ★ 8 repo stars

From the same set: [gupsammy/claudest](https://affpapa.org/en/nevibecode/by/gupsammy/claudest.md) — 47 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
