# Memory System

> Persist and recall project-local memory. WHEN: user says "remember this", "forget", "recall what we decided", "persist this preference", or references memories/, MEMORY.md, or a topic note. USE FOR: initializing a portable memories/ store, listing or searching saved memories, editing MEMORY.md, or distinguishing a skill from a memory file. Do not load for ordinary project file I/O, git, or ephemeral scratch.

- Skill: `vril-labs/memory-system` (Agent Skill, multi-file: 25 files)
- Install (CLI): `npx get-skill add vril-labs/memory-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vril-labs/memory-system/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: VRIL-LABS (https://skillmd.com/u/vril-labs)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/vril-labs/memory-system

---


# Memory System

This skill's persistence layer for project-local memory, at `<project_root>/memories/`, via `scripts/memory <cmd>` (backed by `references/memory_tool`, the deterministic source of truth for this layer — never modify its output or reimplement it). It doesn't assume the host has no other memory mechanism; if one exists, treat this as an additional, file-based layer alongside it. Stdout is JSON; re-`read` to confirm on-disk state.

Since 1.1.0, `init` also creates a hidden `<project_root>/.memsys-db` (SQLite + FTS5, `journal_mode=DELETE`, one file, no `-wal`/`-shm`) — the regenerable index and search plane. Markdown stays the source of truth.

Start here, in order:

1. [references/protocol.md](references/protocol.md) — the full ingest → retrieve → reason → reflect → execute → package workflow, plus commands and quick-start invocations.
2. [references/layout.md](references/layout.md) — store layout and what to load for a given query.
3. [references/when-to-save.md](references/when-to-save.md) — classify: skill vs. index vs. topic vs. reject, and skills-vs-memory routing.
4. [references/constitution.md](references/constitution.md) — hard rules (never skip secret-scan, never exceed 200 lines, never write outside `memories/`, never enumerate via bash, never WAL the ledger).
5. [references/memsys-db.md](references/memsys-db.md) — the `.memsys-db` ledger contract: schema, `search`/`reindex`/`forget`, and why the DB never outranks markdown.
6. [references/examples.md](references/examples.md) — worked examples: happy path, secret rejection, overwrite recovery.

Verify the install with `scripts/memory selftest` before first use.

