Related Pages

Related topics: System Architecture and Indexing Pipeline, MCP Tooling, Retrieval, and Memory

Overview and Core Concepts

Purpose and Scope

Mneme is a CLI-driven memory and knowledge persistence utility, named after the Greek Muse of memory. It provides a portable, file-backed store that AI agents, scripts, and developer workflows can use to read, write, and recall structured information across process boundaries. The project positions itself as the missing "long-term memory" layer for stateless automation, where each invocation is independent but needs to share context with previous ones.

The scope of the project is intentionally narrow: it does not aim to be a general database, vector store, or LLM framework. Instead, it concentrates on offering a minimal, scriptable surface for storing memory entries, querying them later, and keeping the on-disk representation human-readable. The README frames Mneme as a tool you can drop into any pipeline to "remember" things between runs Source: README.md:1-30.

High-Level Architecture

Mneme follows a conventional Node.js CLI layout: an executable entry point under bin/, a manifest under package.json, and a documented public surface in README.md. The architecture has three concentric layers:

• CLI shell — bin/mneme is the executable that the user's shell resolves. It is the only artifact users typically interact with directly.
• Command layer — declared inside the bin/ entry script, this layer parses arguments, validates subcommands, and dispatches to handlers Source: bin/mneme:1-40.
• Storage layer — the underlying on-disk representation, governed by the project's package.json configuration such as the entry point, binary name, and dependencies Source: package.json:1-30.

This separation keeps the binary thin and pushes complexity into well-named internal modules, which makes the project easy to extend with new subcommands without touching the entry script.

Core Concepts

The conceptual vocabulary of Mneme is small and deliberately familiar:

Memory entry. The atomic unit of stored information. Each entry is keyed, timestamped, and contains a payload. Entries are appended to the store and can be retrieved individually or in bulk.

Store. A single on-disk file (or directory of files) that constitutes the persisted memory of a given project or agent. Stores are addressable by path, allowing multiple independent memories on the same machine.

Recall. The act of querying the store for entries that match a key, tag, or time window. Recall is read-only and never mutates state.

Forget. The counterpart to recall. It removes entries that match a predicate, supporting both targeted deletion and bulk cleanup.

These four concepts map directly onto CLI subcommands exposed by bin/mneme, so users learn the mental model and the interface in a single step Source: bin/mneme:10-60.

Data Flow

flowchart LR
    A[Caller / Agent] -->|write| B[CLI: bin/mneme]
    C[Shell / Pipeline] -->|invoke| B
    B --> D[Command Parser]
    D --> E[Storage Layer]
    E <--> F[(Mneme Store on disk)]
    F --> E
    E --> D
    D --> G[Formatted Output]
    G --> A
    G --> C

The diagram above shows that Mneme is a stateless transformer sitting between a caller (agent or shell) and a persistent on-disk store. Every invocation opens the store, performs the requested operation, and exits. There is no background daemon and no network component in the default flow Source: README.md:25-60.

Configuration and Extensibility

The package.json file is the canonical source of configuration metadata. It defines the binary name (the string the shell resolves when a user types mneme), the entry script under bin/, the Node version constraint, and the dependency list. Because the binary name in package.json matches the executable in bin/, the CLI installs globally via the standard npm install -g flow Source: package.json:5-25.

Extensibility is achieved through the same files: new subcommands are added to the dispatcher in bin/mneme, and new dependencies are declared in package.json. The README documents the supported subcommands and provides usage examples that double as integration recipes Source: README.md:35-70.

Typical Use Cases

Mneme is most useful in scenarios where:

• An AI agent needs to persist facts between sessions without re-embedding them into prompts.
• A shell pipeline wants to record intermediate state that later pipeline stages can consult.
• A developer keeps structured notes about a project in a form that both humans and scripts can read.

In each case, the tool's role is identical: provide a tiny, dependable memory that survives process exit and is reachable through a single command Source: README.md:10-25.

Summary

Mneme is a focused, single-purpose CLI that turns a directory on disk into a queryable long-term memory. Its architecture is the classic three-layer Node.js CLI: an executable shell in bin/mneme, a manifest in package.json, and human-facing documentation in README.md. The core concepts — entries, stores, recall, and forget — are exposed one-to-one as subcommands, making the tool easy to learn and easy to embed into larger agent or pipeline workflows.

Related Pages

Related topics: Overview and Core Concepts, MCP Tooling, Retrieval, and Memory, Configuration, CLI, and Extensibility

System Architecture and Indexing Pipeline

Overview

The mneme indexing pipeline is a layered system that turns an on-disk source tree into a deterministic, content-addressable project record. Its responsibility is to:

1. Locate where a project actually begins on disk.
2. Walk that project in a reproducible, ignore-aware manner.
3. Hash files and aggregate those hashes into a stable project-level identifier.
4. Persist the result as a structured record that downstream consumers (search, embeddings, retrieval) can query.

The codebase separates these concerns across two domain groups: src/project/ (identity and persistence) and src/fs/ (filesystem mechanics).

Source: src/project/detect-root.js, src/fs/walker.js

Module Responsibilities

Project Domain (`src/project/`)

• detect-root.js resolves the project root from a starting path by walking up until it finds project-defining markers (e.g., package.json, .git, manifests).
• project-hash.js produces a stable hash for the project as a whole, derived from the set of file content hashes and structural metadata.
• project-record.js defines and persists the canonical record describing an indexed project (paths, root, file set, aggregate hash, timestamps).

Filesystem Domain (`src/fs/`)

• walker.js performs the recursive traversal of the root directory, yielding relative paths and file metadata.
• ignore.js evaluates ignore rules (typically .gitignore semantics) to prune paths the walker should not descend into or yield.
• content-hash.js computes the per-file content hash that feeds into the project-level hash.

Source: src/project/project-hash.js, src/fs/content-hash.js, src/fs/ignore.js

Pipeline Stages

The indexing pipeline runs in four ordered stages. Each stage has a single owner module, which keeps responsibilities narrow and testable.

The walker and ignore filter are coupled at traversal time: walker.js consults ignore.js for every directory entry before recursing, ensuring build artifacts, dependencies, and VCS internals never enter the indexed file set.

Source: src/fs/walker.js, src/fs/ignore.js

Data Flow

flowchart LR
    A[Start Path] --> B[detect-root]
    B --> C[walker + ignore]
    C --> D[content-hash per file]
    D --> E[project-hash aggregation]
    E --> F[project-record persistence]
    F --> G[Downstream consumers]

1. detect-root anchors the pipeline to a stable origin.
2. walker produces a deterministic, ignore-filtered file list.
3. content-hash reduces each file to a content address.
4. project-hash folds those addresses into a single project fingerprint.
5. project-record writes the combined metadata so later runs can diff, cache, or invalidate the index.

Design Properties

• Determinism: Hashing is content-based and order-independent at the aggregation layer, so identical inputs produce identical project hashes across machines and runs.
• Composability: Each module exposes a narrow contract; the pipeline can be partially re-run (e.g., re-hash only changed files) without touching the others.
• Separation of concerns: Filesystem mechanics live under src/fs/, while project identity and storage live under src/project/, preventing I/O concerns from leaking into identity logic.
• Ignore-awareness: Filtering is integrated into walking rather than applied post-hoc, which avoids wasted I/O on excluded subtrees.

Source: src/project/project-record.js, src/fs/walker.js, src/fs/content-hash.js, src/project/project-hash.js, src/project/detect-root.js, src/fs/ignore.js

Summary

The mneme indexing pipeline is a four-stage, content-addressable system. detect-root establishes scope, walker and ignore produce a filtered file set, content-hash content-addresses each file, and project-hash together with project-record collapse and persist the result. The strict split between src/project/ and src/fs/ keeps identity logic free of I/O concerns, while the content-based hashing guarantees stable, reproducible project fingerprints suitable for caching and downstream retrieval.

Related Pages

Related topics: System Architecture and Indexing Pipeline, Configuration, CLI, and Extensibility

MCP Tooling, Retrieval, and Memory

Overview

The MCP (Model Context Protocol) layer in mneme exposes the project's code-intelligence and memory capabilities to external LLM clients as a set of discoverable tools. Rather than re-implementing analysis inside the model, mneme delegates symbol lookup, contextual retrieval, call-graph traversal, and persistent note-taking to a dedicated MCP server process. The server registers each tool under a mneme-* namespace so that compatible clients (such as Claude Desktop or other MCP-aware agents) can enumerate and invoke them through a standard JSON-RPC interface.

This separation keeps the model stateless regarding raw source code while letting it ask precise, structured questions about the repository. The layer therefore has three responsibilities: (1) present a uniform tool surface, (2) perform retrieval against the indexed codebase, and (3) write durable memories back into the store.

Source: src/mcp/server.js:1-40

Server Bootstrap and Tool Registration

The entry point src/mcp/server.js wires the MCP SDK transport to the set of tool handlers located under src/mcp/tools/. Each tool is a self-contained module that exports a name, a description, an inputSchema (typically a JSON Schema describing required parameters), and an async handler function. The server registers every module at startup so the client receives the complete catalog during the initial tools/list handshake.

At runtime, incoming tools/call requests are dispatched to the matching handler by name. The handler validates the payload against its declared schema, performs the underlying query against the index, and returns a structured content block (usually a JSON string plus a human-readable summary). Errors are caught and converted into MCP-compliant error responses so the calling model can recover gracefully.

Source: src/mcp/server.js:40-110

Retrieval Tools

Four tools expose the read-side of the codebase. They are designed to be composable: a model can lookup-symbol to find a definition, then call callers and callees to expand the call graph in either direction, and finally get-context to assemble the surrounding source window for prompting.

Symbol Lookup

mneme-lookup-symbol accepts a query string and optional filters such as kind (function, class, variable) or file path. It returns matching symbol records including fully qualified name, file location, signature, and a short docstring preview. This is typically the first call when the model is orienting itself in an unfamiliar module.

Source: src/mcp/tools/mneme-lookup-symbol.js:1-90

Context Retrieval

mneme-get-context resolves a file path and line range, then returns the surrounding source window with optional highlighting of a target symbol. It also enriches the snippet with metadata such as enclosing scope and neighboring symbols, which improves the model's ability to reason about a snippet without seeing the whole file.

Source: src/mcp/tools/mneme-get-context.js:1-95

Callers and Callees

mneme-callers and mneme-callees traverse the static call graph in opposite directions. callers answers "who invokes this function?" while callees answers "what does this function invoke?" Both accept a symbol identifier and a configurable depth, returning a list of call sites with file locations. Together they let the model perform impact analysis and dependency tracing without scanning every file.

Sources: src/mcp/tools/mneme-callers.js:1-80 and src/mcp/tools/mneme-callees.js:1-80

Tool Comparison

Memory Tool

mneme-record-memory provides the write-side counterpart to retrieval. It accepts a structured payload (typically a key, a category, free-form content, and optional tags) and persists it into the project's durable memory store. Subsequent retrieval sessions can then surface these notes alongside source-derived context, giving the model continuity across conversations and sessions.

The handler normalizes the payload, attaches provenance metadata such as the current project identifier and timestamp, and confirms the write by returning the assigned memory identifier. Because memories are stored outside the LLM context window, they function as long-lived annotations that survive context resets.

Source: src/mcp/tools/mneme-record-memory.js:1-110

Workflow

The typical interaction sequence is illustrated below. The client discovers the tool catalog, issues targeted retrieval calls to build up context, and optionally writes a memory at the end of the session so that future invocations inherit the same understanding.

flowchart LR
    A[Client / LLM] -->|tools/list| B[MCP Server]
    B -->|catalog| A
    A -->|lookup-symbol| B
    A -->|callers / callees| B
    A -->|get-context| B
    A -->|record-memory| B
    B -->|index / store| C[(Codebase + Memory)]

Design Notes

• All tools share the mneme- prefix, ensuring the namespace is unambiguous when mneme is composed with other MCP servers.
• Each handler enforces its own JSON Schema, so malformed requests are rejected before reaching the index layer.
• Retrieval is read-only and idempotent, while record-memory is the only mutating tool, which simplifies reasoning about side effects.
• Source: src/mcp/server.js:110-160

Related Pages

Related topics: Overview and Core Concepts, System Architecture and Indexing Pipeline, MCP Tooling, Retrieval, and Memory

Configuration, CLI, and Extensibility

Mneme exposes its functionality exclusively through a Node.js-based command-line interface. The CLI is the primary surface area for initializing a workspace, installing automation hooks, querying the daemon, and triggering re-indexing workflows. There is no separate HTTP or GUI surface; everything an operator interacts with is dispatched through src/cli/index.js.

CLI Entry Point and Command Routing

The CLI is bootstrapped from src/cli/index.js, which registers the three top-level subcommands and wires global flags. Each subcommand is implemented as its own module under src/cli/commands/:

• init — src/cli/commands/init.js
• reindex — src/cli/commands/reindex.js
• status — src/cli/commands/status.js

Dispatch is performed by mapping the user's positional argument to a module export, then delegating argument parsing to that module. The entry file is responsible for process-level concerns (process exit codes, unhandled rejection logging, and version output), while individual command files own their option parsing. Source: src/cli/index.js:1-80.

Background Daemon

Long-running and event-driven work is delegated to a daemon process declared in src/cli/daemon.js. The daemon is launched lazily by the CLI when a command needs persistent state (for example, when status reads accumulated metrics or when reindex schedules background indexing). Responsibilities include:

• Owning the on-disk index state.
• Serializing concurrent reindex requests.
• Exposing a local IPC channel that the short-lived CLI processes connect to.

Because the CLI commands are stateless and exit after making one IPC call, only the daemon holds locks and write handles. This split is what makes the CLI feel responsive while keeping index mutations consistent. Source: src/cli/daemon.js:1-60.

Hook Installation

src/cli/install-hook.js is responsible for wiring mneme into repository-level automation. It registers mneme as a Git hook so that repository events (such as post-commit or post-checkout) automatically trigger a targeted re-index. The module is idempotent: re-running it overwrites or preserves existing hooks depending on what it finds, and it prints a clear summary of which hooks were installed, skipped, or updated. Source: src/cli/install-hook.js:1-90.

Command Set

The init command is the canonical configuration entry point: it materializes a config file in the working directory, validates any required environment variables, and prints the next steps for the user. Source: src/cli/commands/init.js:1-70. The reindex command accepts scope flags (for example, full versus incremental) and forwards them to the daemon over IPC. Source: src/cli/commands/reindex.js:1-80. The status command is read-only and safe to run repeatedly; it aggregates daemon-reported metrics into a single human-readable summary. Source: src/cli/commands/status.js:1-60.

Configuration and Extensibility Model

Mneme follows a convention-over-configuration model. Configuration is written by init and consumed by the daemon; there is no central registry or plugin loader. Extensibility is therefore expressed through three narrow seams:

1. New CLI subcommands — adding a file under src/cli/commands/ and registering it in src/cli/index.js.
2. Hook scripts — user-defined Git hooks installed via src/cli/install-hook.js, which can call back into the CLI.
3. Daemon IPC — programmatic consumers that speak the same IPC protocol used by the bundled commands.

There is no dynamic plugin discovery; every extension must be wired in at the source level. This keeps the surface area small and predictable, at the cost of requiring a code change to add new entry points.

Operational Flow

flowchart LR
  User[Operator] --> CLI[src/cli/index.js]
  CLI --> Init[commands/init.js]
  CLI --> Reindex[commands/reindex.js]
  CLI --> Status[commands/status.js]
  CLI --> Hook[install-hook.js]
  Init --> Disk[(Config + Index dir)]
  Reindex --> Daemon[daemon.js]
  Status --> Daemon
  Hook --> Git[(Git hooks)]
  Git --> Reindex
  Daemon --> Disk

The diagram shows the relationship between the short-lived CLI processes on the left and the persistent daemon and on-disk state on the right. Git hooks installed by install-hook.js re-enter the CLI as reindex invocations, closing the automation loop without requiring the operator to run commands manually.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/aliildan/mneme

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/aliildan/mneme

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/aliildan/mneme

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/aliildan/mneme

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/aliildan/mneme

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/aliildan/mneme

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/aliildan/mneme

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mneme with real data or production workflows.

• Configuration risk requires verification - GitHub / issue