Memnest

memnest

한국어 | Install | Use it | Operations

Your coding AI forgets everything when the session ends. Memnest lets it look up what you decided before, and why, from the original conversation instead of an AI-written summary.

• Original text, not summaries. No LLM rewrites your history. Saving and searching call no model API, so there is no API key and no extra token bill. Every result carries a source ID you can open.
• One memory for every coding AI. Claude Code, Codex, Cursor, and pi connect to the same local service. Decide something in Claude Code, look it up from Codex.
• Stays on your machine. One Rust binary with SQLite and a local multilingual embedding model. Credentials go to a separate encrypted vault.

Install

curl -fsSL https://raw.githubusercontent.com/Blue-B/memnest/main/core/scripts/install.sh | bash

This installs the latest release for your user, starts the server and conversation watcher, and adds Memnest to the Claude Code, Codex, and Cursor configurations it finds. Existing configuration is backed up first, and the restore command is printed.

Requirements: macOS on Apple Silicon, or Linux with systemd on x86_64 (glibc 2.35+, e.g. Ubuntu 22.04, Debian 12) or Arm64 (glibc 2.39+, e.g. Ubuntu 24.04). Python 3 is needed for setup. The first write or search downloads an embedding model of about 1.1 GB, and embedding can use about 1.9 GB of RAM.

Read the script first, pin a version, or upgrade

curl -fsSL https://raw.githubusercontent.com/Blue-B/memnest/main/core/scripts/install.sh \
  -o /tmp/memnest-install.sh
less /tmp/memnest-install.sh
VERSION=v0.4.3 bash /tmp/memnest-install.sh --user

Before upgrading an existing installation, back up memory.db together with master.key.

See it work

Two separate clients, one local store: the record saved through MCP comes back with the same ID from an independent search. Reproduce it on your own machine.

When to use it

Use the accumulated record for questions such as:

Why did we switch task managers? Find the discussion behind that decision.

What deployment approach did we last settle on for this project, and why?

What did we try the last time this error happened?

The AI searches memory, reads the relevant source, and uses it to answer. Results include source IDs so you can check the evidence. These are example requests, not an autonomous demo or a guarantee that an answer will be found.

For a few rules that should apply every time, AGENTS.md or CLAUDE.md is simpler. Memnest is for a growing history of conversations and decisions that you want to look up when needed.

Connect pi

With the core running, install the matching extension:

# Published extension for core 0.4.x
pi install npm:pi-memnest@0.4.0

# Or connect a reviewed source checkout
pi install ./pi-extension

If Memnest is already registered from another source, remove that registration first to avoid loading it twice. Use /memnest in pi to check the connection. See extension settings.

Local development: vault tool settings

The extension exposes only the five memory tools by default. To let pi store and retrieve credentials with secret_set, secret_get, secret_list, and secret_delete, enable the vault tools before starting pi:

export MEMNEST_EXPOSE_SECRET_TOOLS=1
pi

Restart pi after changing the variable; /reload alone cannot change the running process environment. /memnest reports whether the vault tools are available and shows this activation hint when they are hidden.

Other MCP clients connect to http://127.0.0.1:3111/mcp. See connection examples, other environments and source installation, and upgrade and recovery. Intel Macs need a source build.

Use it

Ask your connected AI to look up a previous conversation or decision. Automatic recall is off by default; you can start by requesting a search when you need one. See extension settings to enable automatic recall.

Clients that call tools directly use this flow:

memory_search(query="reason for switching task managers")
memory_get(id="<ID returned by search>")

Five tools cover saving, searching, reading, correcting, and deleting. Use memory_remember to explicitly save an important decision. When a fact changes, save its replacement with supersedes=<old ID> to link it to the earlier record.

When the host provides the current directory, searches include that workspace and the shared playbook. Specify project=all for a deliberate cross-project search. See source reading for long records and nearby conversation entries.

Conversations from before installation are not all imported automatically. Select the original files you need with history import.

Source-backed coding records (0.4.0)

Save an approach as proposed, failed, or reported success without treating that report as verification. Optionally attach selected local files with memory_remember(code_files=["relative/file"]), then request memory_get(check_code=true) when you want to compare their bytes. Unrelated edits do not trigger warnings. See code evidence.

Optional team access adds named project grants, audit and retention. A free local comparison records where Memnest did and did not perform well; it does not claim universal accuracy superiority.

Important limits

• Retrieval is not truth checking. Search can miss a relevant record. Memnest cannot determine whether an old decision still holds. A following-source hint is not a verified reply relationship.
• Capture is selective. It stores visible conversation text, not reasoning, tool traffic, images, or subagent conversations. It does not import ChatGPT's or Claude's built-in memory.
• Storage is local; your connected AI answers. Default storage/search makes no generative LLM calls. Explicit evidence_only=true opts in to a configured local source-selector model, whose judgment remains unverified. A cloud AI provider receives retrieved text that you send to its model.
• Regular memories are not encrypted. Redaction handles known credential patterns, not every possible secret. Do not expose port 3111 directly to the internet.
• A web connector is a network path into your memories. ChatGPT and Grok connectors need a public URL, retrieved text reaches the provider's servers, and that URL acts as a credential. See web connectors.
• Deletion is not immediate erasure. Records default to 30 days in trash. New plaintext archives are off by default; old archives, backups and external transcripts may still retain copies. See security and deletion limits.

Documentation and checks

One Rust service stores source records in SQLite and searches with BM25 plus local multilingual embeddings. Search indexes can be rebuilt from the source records.

• Web connectors for ChatGPT and Grok, real-client validation and reproducible shared-store demo
• Following-source checks and limits, retrieval evaluation, a recorded three-question recall check
• Design decisions, operations and backups, contributing
• Latest release and changelog

License

MIT © Blue-B