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 mem-cli wizard --global once per machine.
3. Run mem-cli wizard inside each repository.
4. Make sure a default writer.id is configured for write-capable commands.
5. Start mem-service.
6. Open the TUI or web UI.

Debian:

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

macOS:

brew install --HEAD ./packaging/macos/homebrew/memory-layer.rb
mem-cli wizard --global
cd /path/to/your-project
mem-cli wizard
mem-cli service enable
mem-cli tui

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

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

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

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
• Embedding Operations
• Scan Command
• Commit History

Developer Docs

• Developer Documentation Index
• 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 mem-cli -- wizard
cargo run --bin mem-service
cargo run --bin mem-cli -- tui --project memory

Optional watcher:

cargo run --bin memory-watch -- run --project memory

Packaging and implementation details now live under Developer Documentation.