Memory Layer

Memory Layer is a local knowledge base built first for coding agents such as Codex CLI and Claude Code, while still working well for normal developers.

It captures durable project knowledge, stores it in PostgreSQL with pgvector, and makes it searchable in a TUI or browser so important context does not disappear into chat history, terminal scrollback, or old commits.

It supports multiple developers, multiple projects, and multiple coding agents at the same time through a distributed watcher system and a shared memory backend.

Table of Contents

• Quick Start
• What It Does
• Documentation
• Development

Quick Start

The fastest path is:

1. Install the package.
2. Run memory wizard --global once per machine.
3. Run memory wizard inside each repository.
4. Let Memory Layer auto-derive a writer identity, or set writer.id only if you want a custom shared label.
5. Start memory service run or enable the packaged service.
6. Open the TUI or web UI.

Debian:

sudo dpkg -i memory-layer_<version>_amd64.deb
memory wizard --global
cd /path/to/your-project
memory wizard
sudo systemctl enable --now memory-layer.service
memory tui

macOS:

brew tap 3vilM33pl3/memory https://github.com/3vilM33pl3/memory
brew install --HEAD 3vilM33pl3/memory/memory-layer
memory wizard --global
cd /path/to/your-project
memory wizard
memory service enable
memory tui

For the full onboarding flow, prerequisites, upgrade path, and troubleshooting, use Getting Started.

For semantic-search maintenance and model switching, use Embedding Operations.

For shareable backup/restore bundles, use Memory Bundles.

For watcher health states, recovery behavior, and the TUI watcher views, use Watcher Health.

For bootstrap, diagnostics, and the main write path, use Wizard And Bootstrap, Service Commands, Doctor Diagnostics, and Remember Command.

Most mutating memory commands support --dry-run so you can preview writes, service actions, and plan/checkpoint flows before applying them.

For a visual walkthrough of the interface, use the TUI Guide.

What It Does

• stores project memory in PostgreSQL with pgvector-backed chunk embeddings
• supports both primary and relay service modes
• keeps memory scoped per project while supporting multiple developers, writers, and agents
• captures raw evidence and curates durable memory from it
• combines lexical search, vector search, and related-memory links
• supports re-embedding when you switch embedding models without losing older embedding spaces
• uses distributed watchers to track active projects and feed evidence into the shared memory system
• provides a TUI and a browser UI
• can scan a repository for durable project knowledge
• can import git commit history as searchable evidence
• can export and import shareable project memory bundles

Project-local customization now has two layers:

• .mem/ for runtime overrides and generated state
• .agents/memory-layer.toml for project-owned memory behavior such as include/ignore paths and future analyzers/plugins

Documentation

User Docs

• User Documentation Index
• Getting Started
• TUI Guide
• Embedding Operations
• Memory Bundles
• Watcher Health
• Resume Briefings
• Wizard And Bootstrap
• Init Bootstrap
• Service Commands
• Doctor Diagnostics
• Health And Stats
• Query Command
• Checkpoint Workflow
• Capture Command
• Remember Command
• Curate Command
• Repository Index
• Scan Command
• Commit History
• Archive Command
• Automation Commands

Developer Docs

• Developer Documentation Index
• How Skills Work
• Architecture Overview
• How Memory Layer Works
• Hidden Memory Daemon

Development

For working on this repository itself, start with the developer docs. The short version is:

cargo run --bin memory -- wizard
cargo run --bin memory -- service run
cargo run --bin memory -- tui --project memory

Optional watcher:

cargo run --bin memory -- watcher run --project memory

Packaging and implementation details now live under Developer Documentation.