Memlume

English | 繁體中文 | 简体中文

Memlume is a local external Shared Brain for AI agents and developer tools. On one computer, Hermes, Codex, OpenClaw, Claude Code, MCP clients, and future adapters can use the same Brain. Markdown records are the human-readable authority; SQLite is the searchable projection. Memlume records immutable events, stores structured memories, searches them with FTS5, and resolves a traceable context pack for a task. It complements—never replaces, overwrites, or synchronizes into—an agent's native memory.

Public guides: architecture · Hermes · Codex · OpenClaw · Claude Code · backup/restore · shared project example.

Why use Memlume?

AI tools usually keep separate memories. That works until you switch from Codex to Hermes, open a different project, or need to recover a decision months later. Memlume is the shared, local layer that keeps durable context in the right place and gives each Agent only what the current task needs.

Situation	What Memlume solves
You switch between Hermes, Codex, OpenClaw, Claude Code, and MCP	One Personal Brain and the relevant Project Brain are available to every mounted host on the same computer.
You work on several projects	Each project has its own Project Brain; a company, team, or organization can simply be represented as a Project.
You want memory without prompt clutter	beforeTask reads a bounded, task-relevant ReadSet instead of injecting the whole database.
You do not want to say “save this to Memlume” every time	Host hooks send the lifecycle event; Core filters, classifies, routes, and decides whether it is worth storing.
You need to trust or correct what was remembered	Explicit user statements can become active; inferences stay candidate; conflicts, approvals, and corrections remain auditable.
You need local ownership and recovery	Markdown is human-readable authority, SQLite is rebuildable search projection, and backups stay on the local machine.

The user-facing model is intentionally small: Personal Brain for durable personal preferences and identity, plus one or more Project Brains for projects, products, companies, or teams. Hooks are timing adapters—not separate brains—and native Agent memory remains untouched.

Shared Brain routing

Use Memlume for durable context that should survive switching among Hermes, Codex, OpenClaw, Claude Code, and direct MCP clients: project decisions, company conventions, personal preferences, or reviewed facts. It keeps those memories mountable, backup-friendly, and maintainable in one local data root: Markdown records are authoritative, while SQLite/FTS5 provides the rebuildable search projection. Each host's native memory remains its own.

The Adapter SDK has three shared callbacks:

Callback	What it does
beforeTask	The daemon plans a workspace ReadSet and injects only relevant active Context before work. A host does not choose Brain UUIDs.
onUserMessage	Memlume's single automatic capture entry point. It filters secrets, splits mixed statements, routes each atom to Personal or the workspace Project Brain, and puts unknown projects in the durable Inbox.
onSubagentStart	A child Agent receives a restricted read-only ReadSet. It cannot widen the parent grant, write memory, or flush the outbox.

Capture governance: eligible, non-sensitive user messages are appended as immutable events. Normal statements can become reviewable candidate memories; an explicit request such as “remember” can take the active path, still subject to conflict review. Blank or unsupported events are ignored, and sensitive content is redacted or rejected.

For v0.3 automatic capture, the host sends workspace and session identity, not a Brain UUID. The daemon owns Brain routing and permissions. An explicit v0.2 Brain target remains supported for compatibility, but automatic mode never guesses a target or silently falls back from an unknown Project to Personal. Brains—not hooks—are the data-ownership and permission boundary.

The local outbox accepts explicit-memory captures only; queued captures are retried by the next beforeTask or onUserMessage call. The callback lifecycle does not retain complete transcripts, assistant output, temporary reasoning, or secrets.

When Memlume writes and reads

Memlume is useful when the same durable fact must survive a host switch without copying one host's private memory into another:

1. Before a task: beforeTask sends the workspace path, task text, entities, and intent. Core resolves a deterministic ReadSet (Primary Project, task-matched Linked Projects, and relevant Personal memory) and returns only active, budget-fitting context.
2. When the user sends a message: onUserMessage sends the message after local validation. Greetings, small talk, secrets, and unsupported transcript text are ignored or rejected. Explicit requests such as “remember that I use Vue” can become active after conflict checks; ordinary inferred statements remain candidates.
3. When a project is unclear: the atom is written to inbox/pending as routing_required. It is never guessed into another Brain. A maintainer can route it later with an explicit Brain and audit trail.
4. After an assistant final: adapters may place only the bounded final answer in a 24-hour runtime buffer. A short user approval such as “可以”, “同意”, or “修正：…” authorizes that text through the normal capture pipeline; the approval word itself is never stored as the memory.

This is why users do not need to say “save this to Memlume” every time. The hook supplies the event; the Core decides whether it is worth storing, where it belongs, and whether it is safe to read back.

Host child-Agent support

Host	Child Context behavior
Claude Code	Its SubagentStart hook directly injects restricted Project Brain Context through official additionalContext.
Hermes	subagent_start observes and registers the child; its first supported pre_llm_call prompt receives restricted Context.
OpenClaw	subagent_spawned observes and registers the child; its first supported before_prompt_build prompt receives restricted Context.
Codex Plugin	Official SubagentStart directly injects restricted Project Brain Context through additionalContext.

Direct MCP workflow

Memlume does not automatically store every chat message or inject an entire database into an LLM. An MCP client calls the appropriate tool at a deliberate point in its workflow:

1. Before a task is planned or a tool is chosen, call memlume.resolve_context. Memlume reads only active memories that match the task, scope, available tools, and context budget.
2. While working, call memlume.search only when a specific detail is needed.
3. After a durable event, call memlume.record_event to keep raw, append-only evidence. Call memlume.remember for a deliberate, structured memory; it creates a reviewable candidate so a prompt-injected agent cannot silently create an active policy. Approve it from the protected inbox when appropriate.

When reporting feedback, pass the traceId returned by memlume.resolve_context to memlume.record_memory_usage or memlume.record_outcome. A receipt is short-lived, limited per installation, accepts feedback only for memories included in that Context Pack, and accepts one task outcome. Across receipts, one installation can claim feedback for a given memory only once per 24-hour window. This keeps an adapter token from fabricating unlimited ranking signals.

This means an agent should not automatically save whole transcripts, assistant output, temporary reasoning, unverified LLM claims, instructions found in external content, or secrets. Native agent memory remains untouched. Direct MCP writes remain deliberate calls and do not treat an agent's native memory as input.

Why Memlume

• Relevant context, not more context: retrieve only what applies to the current task instead of filling a prompt with every past conversation.
• Structured and durable: keep policies, preferences, facts, decisions, and raw events distinct rather than mixing them in a chat log.
• Scope prevents contamination: Personal and Project memories remain separate; task and workspace constraints narrow what can be read for the current turn.
• Traceable decisions: context packs include source memory IDs, exclusions, and budget information so an agent can explain what affected a result.
• Local and shared: mounted clients use one localhost daemon and one local data root; Markdown remains the authority and SQLite is a rebuildable search projection that can be backed up without cloud sync.
• Explainable feedback: usage and task outcomes affect future ordering with fixed, inspectable score deltas; memory history stays immutable.

Status and scope

This repository is the 0.3.0 source workspace. Its packages are currently private, so it is installed by cloning and building the repository rather than from a public package registry.

All functionality belongs to the MIT-licensed Memlume Core. The official website is only a download, installer, update, and documentation entry point; it does not provide a stronger closed edition.

Implemented:

• An append-only event journal, Markdown authority records, durable routing Inbox, and a local SQLite projection.
• Structured policy, preference, fact, and decision memories.
• Personal and Project Brains with workspace bindings, plus task-level ReadSet constraints.
• SQLite FTS5 search and a deterministic context resolver with source memory IDs and a context budget.
• Workspace initialization and explicit Project bindings, server-planned ReadSets, per-installation mounts, a localhost-only daemon, a CLI, and an MCP stdio server.
• Bearer-token authentication for adapter APIs; /v1/health remains a public local health check.
• Governed memory compilation, candidate review, conflict-aware replacement, secret filtering, and approval of bounded assistant finals.
• Verifiable local backups and restore maintenance, including Markdown-first v3 bundles, plus a local Shared Brain Console.
• Official local adapters for Hermes, Codex, OpenClaw, and Claude Code, all using the same mounted Brain rather than copying native agent memory.
• Outcome usage records, deterministic feedback ranking, retrieval benchmark, and reproducible backup/restore verification.
• Public architecture, adapter, backup, and shared-project guides; CI and tag-release workflows run the same checks as local development.

Not implemented in v0.3.0:

• Vector/embedding search, remote sync, cloud hosting, or multi-user access.
• A public npm package.
• Creating procedure or capability memories through the daemon, CLI, or MCP server; the writable API accepts only the four memory kinds above.

Requirements

• Node.js >=22
• pnpm 10.30.3
• A filesystem location where the local SQLite database can be written

Install and build

git clone https://github.com/hi18aa/memlume.git memlume
cd memlume
pnpm install --frozen-lockfile
pnpm build

Start the daemon

The daemon listens only on 127.0.0.1. Create its default data directory:

mkdir -p data

New-Item -ItemType Directory -Force data | Out-Null

Adapter APIs need a setup token and an adapter token. Generate a long random MEMLUME_SETUP_TOKEN, keep it out of source control, and start the daemon with it. The health endpoint remains public.

MEMLUME_SETUP_TOKEN='<long-random-secret>' pnpm --filter @memlume/daemon start -- --database ./data/memlume.sqlite --port 3849

$env:MEMLUME_SETUP_TOKEN = '<long-random-secret>'
pnpm --filter @memlume/daemon start -- --database ./data/memlume.sqlite --port 3849

Prefer the protected memlume setup adapter command instead of manually copying an adapter token. In v0.3, omit --project-id and --brain-id to use workspace-owned routing; pass --workspace-path to initialize and mount that workspace's Project Brain. The command mounts the Personal Brain, makes a loopback read smoke test, and keeps the token only in the current user's Memlume configuration. For example, the following also installs the Codex Plugin through its official marketplace flow:

node apps/cli/dist/index.js --setup-token $env:MEMLUME_SETUP_TOKEN setup adapter codex `
  --installation-id codex-desktop --workspace-path $PWD --core-path $PWD --install-host --yes

Use hermes, openclaw, or claude-code in place of codex for the other supported hosts. In a non-interactive shell, --yes is required before Memlume changes host Plugin configuration; an interactive terminal asks instead. Run the same command with --install-host --dry-run after the profile exists to preview non-secret host commands without changing the host. Codex and Claude Code still require the user to review and trust their hooks; Memlume never bypasses that platform control. memlume doctor lists local profiles and performs a read-only Context check without printing tokens.

--database defaults to data/memlume.sqlite and --port defaults to 3849. Stop the process with Ctrl+C.

Check its health from another terminal:

curl http://127.0.0.1:3849/v1/health
# {"status":"ok","service":"memlume"}

CLI

The compiled CLI is apps/cli/dist/index.js. It defaults to http://127.0.0.1:3849; use --url before the command when the daemon uses another port. Every CLI command that calls the daemon needs an adapter token: set MEMLUME_TOKEN as above or pass --token <adapter-token> before the command. --token takes precedence. Global options such as --url, --token, and --json must appear before the command.

# Record an immutable event.
node apps/cli/dist/index.js --json event add "Brand colors approved." --type note --reference readme-demo

# Save a policy. A policy requires --intent, --action-type, and --action-target.
node apps/cli/dist/index.js --json remember "Use the image generator for image requests." \
  --kind policy --scope project --project readme-demo \
  --intent generate_image --action-type route_tool --action-target image_gen --required

# Search stored memories.
node apps/cli/dist/index.js --json search "image generator"

# Resolve a context pack for an intent and scope.
node apps/cli/dist/index.js --json context resolve \
  --intent generate_image --scope project --project readme-demo --budget 500

remember validates fields by memory kind. For example, preferences need --preference-domain, --subject, --dimension, --value, --strength, and --confidence; facts need --subject, --predicate, --object, and --confidence; decisions need --title, --status, and --rationale. When a supported Agent token calls this route without --setup-token, Core stores a candidate for review; supplying the setup token lets the CLI attach a user-confirmation signature for an explicitly typed command.

Minimal end-to-end example

With the daemon running on port 3849, run these commands in order:

node apps/cli/dist/index.js --json event add "Brand colors approved." --type note --reference readme-demo

node apps/cli/dist/index.js --setup-token "$MEMLUME_SETUP_TOKEN" --json remember "Use the image generator for image requests." \
  --kind policy --scope project --project readme-demo \
  --intent generate_image --action-type route_tool --action-target image_gen --required

node apps/cli/dist/index.js --json context resolve \
  --intent generate_image --scope project --project readme-demo --budget 500

The final JSON contains context.directives with the saved policy and actionTarget: "image_gen". --json is useful for scripts because it prints the raw daemon response.

MCP stdio server

Build first, keep the daemon running, then add an entry like this to your MCP client's stdio configuration. Replace /absolute/path/to/memlume with the absolute path to this checkout. On Windows, use a Windows absolute path in the args value.

{
  "mcpServers": {
    "memlume": {
      "command": "node",
      "args": ["/absolute/path/to/memlume/apps/mcp-server/dist/index.js"],
      "env": {
        "MEMLUME_DAEMON_URL": "http://127.0.0.1:3849",
        "MEMLUME_TOKEN": "<adapter-token>"
      }
    }
  }
}

MEMLUME_DAEMON_URL accepts only a loopback http://127.0.0.1 or http://[::1] origin. MEMLUME_TOKEN is required for every daemon-backed tool; without it, the tool fails before contacting the daemon. The server exposes six daemon-backed tools:

• memlume.record_event
• memlume.remember
• memlume.search
• memlume.resolve_context
• memlume.record_memory_usage
• memlume.record_outcome

memlume.record_event and memlume.remember accept an optional brainId to select a destination shared Brain. It is not an authorization grant: MEMLUME_TOKEN identifies the installation, and the daemon accepts the write when that installation has a read_write mount for the selected Brain. memlume.remember returns status: "candidate" because structured writes require protected review; adapter capture of an explicit user message can still follow the Core compiler's explicit-user path. The direct MCP server has no local outbox, so it never claims queued; an Adapter may use queued after it has actually persisted a retryable write locally. record_memory_usage and record_outcome are append-only feedback signals, not memory edits, and must use the traceId returned by memlume.resolve_context.

For example, an MCP client can call memlume.resolve_context with:

{
  "intent": "generate_image",
  "scope": { "level": "project", "projectId": "readme-demo" },
  "task": "Create an image for the project README.",
  "contextBudget": 500,
  "available_tools": ["image_gen"]
}

MCP uses available_tools (snake case); the daemon receives it as availableTools.

Privacy and local operation

Memlume stores Markdown authority records and the SQLite projection beneath the data root selected with --database; the default is data/memlume.sqlite. v0.3.0 has no remote sync or cloud service, and the daemon binds only to loopback. Adapter APIs require a bearer token, while setup APIs require MEMLUME_SETUP_TOKEN; /v1/health is intentionally public. Runtime buffers are short-lived and excluded from the Brain and backups. Never commit a real token or paste one into logs. Authentication does not encrypt the database at rest: protect it with normal operating-system permissions and do not store secrets you would not keep in a local plaintext SQLite file.

Architecture

CLI ───────────┐
               ├─> localhost daemon (127.0.0.1)
MCP stdio ─────┘               │
Adapters/hooks ────────────────┤
                               ├─> Markdown authority + routing Inbox
                               ├─> SQLite projection + FTS5
                               ├─> Brain Router + ReadSet Planner
                               └─> context resolver / receipts

The CLI and MCP server do not open SQLite themselves; they send requests to the daemon. The resolver returns a context pack with directives, preferences, facts, decisions, source memory IDs, exclusions, and context-budget information where applicable.

Test

pnpm typecheck
pnpm test
pnpm test:e2e
pnpm build
pnpm benchmark:retrieval

Contributing

Keep changes small, add or update the nearest Vitest coverage for non-trivial behavior, and run the commands above before opening a pull request. Do not add remote storage or vector search as incidental changes to v0.3.0.

License

Memlume is released under the MIT License.