Skip to content
Back to search

memora

Give your AI agents persistent, collective memory — with deduplicating absorb, supersession lineage, semantic search, and a graph UI. Speaks MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/agentic-box/memora with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/agentic-box/memora'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agentic-box--memora/badge.svg)](/listings/agentic-box--memora)

HTML

<a href="/listings/agentic-box--memora"><img src="/api/listings/agentic-box--memora/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Two paths. **pip** is a local stdio child the client spawns. A **container** is a detached HTTP service you start with `up`; with `MEMORA_DATABASES` it serves multiple stores from one process. The LaunchAgent supervises the **proxy**, not the container — after a host restart the listener can come back while its upstream is still stopped. If you are running memora as a service, the container path *is* the install.

pip (local / stdio)

pip install memora-mcp

The PyPI package is **`memora-mcp`** (bare `memora` on PyPI is an unrelated project). Includes cloud storage (S3/R2) and OpenAI embeddings out of the box.

# Optional: local embeddings (offline, ~2GB for PyTorch)
pip install "memora-mcp[local]"

# Latest development version straight from git
pip install "git+https://github.com/agentic-box/memora.git"

Then spawn it from `.mcp.json` with `"command": "memora-server"` (see [Configuration](#configuration)).

Container (HTTP service)

Default runtime is Apple's [`container`](https://github.com/apple/container) CLI. Every container operation `scripts/memora-instance.sh` performs (`build`, `up`, `status`, `logs`, `down`) uses `$MEMORA_CONTAINER_BIN` (default `container`). The generated proxy process does not; it hardcodes `container list`.

**Before the first `build`:**

1. Install Apple's `container` CLI (signed pkg from its GitHub releases). It needs a Mac with Apple silicon **running macOS 26** — Apple does not support older macOS versions for `container`. 2. Start the runtime — Apple's documented first command, which also installs a kernel if none is configured:

   container system start

3. Clone this repo and `cd` into it:

   git clone https://github.com/agentic-box/memora.git
   cd memora

4. Copy the instance template. It ships with `INSTANCE=myinstance` so the later `build`/`up`/`proxy` lines match without renaming. Edit `PORT` and a backend (`STORAGE_URI`, `VOLUME`, or `MEMORA_DATABASES`):

   cp instances/example.env instances/myinstance.env

5. Create the credential file and install the proxy the LaunchAgent will run. `cred_args()` requires a `.mcp.json` whose `mcpServers.memora.env` holds `CLOUDFLARE_API_TOKEN` (D1 access) and the embedding/LLM keys — `up` dies if that file is missing. The script looks for `~/.config/memora/credentials.mcp.json` **if that file exists**, otherwise `~/repos/agentic-box/.mcp.json`. Set `CRED_SOURCE` in the instance file to pick a path. Separately, `proxy` renders a plist whose executable is `$MEMORA_PROXY_BIN` (default `~/.local/libexec/memora/memora_proxy.py`) and whose logs live in `$MEMORA_LOG_DIR` (default `~/.local/var/log`) — nothing creates either on a fresh clone.

   mkdir -p ~/.config/memora ~/.local/libexec/memora ~/.local/var/log
   cp scripts/memora_proxy.py ~/.local/libexec/memora/
   # real values; any key is fine, an absent file is not
   # the default umask is permissive -- chmod 600 keeps other local accounts out
   cat > ~/.config/memora/credentials.mcp.json <<'JSON'
   {"mcpServers":{"memora":{"env":{"CLOUDFLARE_API_TOKEN":"REPLACE","OPENAI_API_KEY":"REPLACE"}}}}
   JSON
   chmod 600 ~/.config/memora/credentials.mcp.json

That JSON is the minimal correct config: both the LLM and embeddings use the default OpenAI host with a real OpenAI key. Do **not** add `OPENAI_BASE_URL` pointing at OpenRouter without the embedding pair from [Embeddings](#semantic-search--embeddings) — OpenRouter has no embeddings endpoint, every embed call 404s, and memora silently falls back to TF-IDF keyword bags while looking healthy.

Then:

./scripts/memora-instance.sh build myinstance   # tags IMAGE from myinstance.env (memora-pilot if IMAGE is unset)
./scripts/memora-instance.sh up      myinstance # runs that same IMAGE
./scripts/memora-instance.sh proxy   myinstance # render the LaunchAgent; run the printed launchctl

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 30 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "memora",
  4. "description": "Persistent semantic memory for Claude Code with knowledge graph visualization",
  5. "owner": {
  6. "name": "agentic-mcp-tools",
  7. "url": "https://github.com/agentic-mcp-tools"
  8. },
  9. "plugins": [
  10. {
  11. "name": "memora",
  12. "description": "Persistent semantic memory for Claude Code — auto-injects relevant context at session start, captures git commits, test results, and research via hooks, and provides 30+ MCP tools for memory management.",
  13. "version": "0.2.20",
  14. "author": {
  15. "name": "agentic-mcp-tools",
  16. "url": "https://github.com/agentic-mcp-tools"
  17. },
  18. "source": "./claude-plugin",
  19. "category": "productivity",
  20. "homepage": "https://github.com/agentic-mcp-tools/memora",
  21. "tags": [
  22. "memory",
  23. "persistence",
  24. "knowledge-graph",
  25. "semantic-search",
  26. "mcp"
  27. ]
  28. }
  29. ]
  30. }
README.md · README · 874 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center"><img src="media/memora_new.gif" width="60" alt="Memora Logo" align="absmiddle"> Memora</h1>
  2. <p align="center"><sub><sub><i>"You never truly know the value of a moment until it becomes a memory."</i></sub></sub></p>
  3. <p align="center">
  4. <b>Give your AI agents persistent collective memory</b><br>
  5. An MCP memory layer for agents: structured storage, semantic retrieval, graph relations, and source-backed cross-session context.
  6. </p>
  7. <p align="center">
  8. <a href="https://github.com/agentic-box/memora/releases"><img src="https://img.shields.io/github/v/tag/agentic-box/memora?label=version&color=blue" alt="Version"></a>
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
  10. <a href="https://github.com/thedotmack/awesome-claude-code"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code"></a>
  11. </p>
  12. <p align="center">
  13. <img src="media/memora-absorb-digest-flow.gif" alt="Memora absorb and digest flow" width="820">
  14. </p>
  15. <p align="center">
  16. <b>Absorb agent work into durable graph memory, then use <code>memory_digest(topic)</code> to retrieve relevant memories, TODOs/issues, related edges, and source IDs.</b>
  17. </p>
  18. <p align="center">
  19. <b><a href="#features">Features</a></b> · <b><a href="#preview">Preview</a></b> · <b><a href="#install">Install</a></b> · <b><a href="#usage">Usage</a></b> · <b><a href="#configuration">Config</a></b> · <b><a href="#multi-database-routing">Multi-DB</a></b> · <b><a href="#container-deployment">Containers</a></b> · <b><a href="#live-graph-server">Live Graph</a></b> · <b><a href="#cloud-graph">Cloud Graph</a></b> · <b><a href="#chat-with-memories">Chat</a></b> · <b><a href="#semantic-search--embeddings">Semantic Search</a></b> · <b><a href="#document-storage">Documents</a></b> · <b><a href="#llm-deduplication">LLM Dedup</a></b> · <b><a href="#memory-linking">Linking</a></b> · <b><a href="#neovim-integration">Neovim</a></b>
  20. </p>
  21. ## Features
  22. **Core Storage**
  23. - 💾 **Persistent Storage** - SQLite with optional cloud sync (S3, R2, D1)
  24. - 🗄️ **Multi-database routing** - One process serves many stores; a workspace reaches its own at `/mcp/<name>` (see [Multi-database routing](#multi-database-routing))
  25. - 📂 **Hierarchical Organization** - Section/subsection structure with auto-hierarchy assignment
  26. - 📦 **Export/Import** - Backup and restore with merge strategies
  27. **Absorb & Lineage**
  28. - 🧬 **Absorb** - Feed facts in; an LLM classifies each against the store (duplicate / update / contradiction / related / new), skips duplicates, links relations, and consolidates related facts — with `dry_run` preview
  29. - 🌱 **Supersession Lineage** - Updates supersede old knowledge instead of deleting it; retrieval follows the chain to the current version by default (`follow` modes: `active`, `latest`, `full_history`)
  30. - Deleting any version retires the whole lineage (a deleted fact cannot reappear as an older version): `follow=latest`/`active` hide every version, `memory_get` on one answers `not_found` with `retired: true` naming the delete ("retired by deleting #N"), `follow=all` still reads it, and adding a `supersedes` edge to a retired id does not restore it.
  31. - `memory_absorb` never supersedes an item record (`metadata.kind = "item-record"` or tag `item-record`): the fact is written and linked `related_to` instead. Todos and issues are protected by the type boundary (a plain fact never supersedes a typed one).
  32. - 🗞️ **Topic Digest** - `memory_digest(topic)` bundles relevant memories, open TODOs/issues, related edges, and source IDs into one retrieval
  33. **Search & Intelligence**
  34. - 🔍 **Semantic Search** - Vector embeddings (TF-IDF, sentence-transformers, OpenAI)
  35. - 🎯 **Advanced Queries** - Full-text, date ranges, tag filters (AND/OR/NOT), hybrid search
  36. - 🔀 **Cross-references** - Auto-linked related memories based on similarity
  37. - 🤖 **LLM Deduplication** - Find and merge duplicates with AI-powered comparison
  38. - 🔗 **Memory Linking** - Typed edges, importance boosting, and cluster detection
  39. **Document Storage**
  40. - 📄 **Structured Documents** - Store markdown documents as searchable fragment trees (claims, plan items, references, risks)
  41. - 🔒 **Fragment Integrity** - Guards against accidental delete/merge/absorb of document fragments
  42. - 🔍 **Granular Search** - Individual claims and findings are semantically searchable while the full document remains retrievable as a unit
  43. **Tools & Visualization**
  44. - ⚡ **Memory Automation** - Structured tools for TODOs, issues, and sections
  45. - 🕸️ **Knowledge Graph** - Interactive visualization with Mermaid rendering and cluster overlays
  46. - 🌐 **Live Graph Server** - Built-in HTTP server with cloud-hosted option (D1/Pages)
  47. - 💬 **Chat with Memories** - RAG-powered chat panel with LLM tool calling to search, create, update, and delete memories via streaming chat
  48. - 📡 **Event Notifications** - Poll-based system for inter-agent communication
  49. - 📊 **Statistics & Analytics** - Tag usage, trends, and connection insights
  50. - 🧠 **Memory Insights** - Activity summary, stale detection, consolidation suggestions, and LLM-powered pattern analysis
  51. - 📜 **Action History** - Track all memory operations (create, update, delete, merge, boost, link) with grouped timeline view
  52. ## JSON API (`/api/v1`)
  53. The server can expose a plain JSON API at `/api/v1/<store>/{health,search,absorb}`
  54. (the wire contract is `contracts/memora-api/v1/`). It is **off unless
  55. `MEMORA_API_TOKENS_FILE`** is set to an absolute path; an unset variable is an
  56. intentional state and is logged at INFO, not ERROR (issue 1131).
  57. The file holds sha256 digests, never tokens. The server opens it
  58. `O_RDONLY | O_NOFOLLOW | O_CLOEXEC` and requires a regular file, no group/other
  59. permission bits and at most 4 KiB, owned by the server's user, under parents
  60. that are not symlinks and not group/world-writable. On a **read-only mount**
  61. (for example the deploy's read-only secrets mount, where rootful docker reads
  62. the operator's file as root and `statvfs` reports `ST_RDONLY`), the owner match
  63. for the file and for its read-only parents is not required; every other check
  64. still applies. A failed reload keeps the last good token set.
  65. `scripts/mint_api_token.sh` mints a token into a new 0600 file and adds its
  66. digest to `api-tokens.json`; `scripts/deploy-memora-all.sh` sets
  67. `MEMORA_API_TOKENS_FILE` when that file is in its secrets directory. Request
  68. semantics (401/403/404) and rotation are in the contract.
  69. ## Preview
  70. <p align="center">
  71. <img src="media/demo.gif" alt="Memora memory graph demo" width="320">
  72. <img src="media/demo2.gif" alt="Memora memory interaction demo" width="320">
  73. </p>
  74. ## Install
  75. Two paths. **pip** is a local stdio child the client spawns. A **container** is a detached HTTP service you start with `up`; with `MEMORA_DATABASES` it serves multiple stores from one process. The LaunchAgent supervises the **proxy**, not the container — after a host restart the listener can come back while its upstream is still stopped. If you are running memora as a service, the container path *is* the install.
  76. ### pip (local / stdio)
  77. ```bash
  78. pip install memora-mcp
  79. ```
  80. The PyPI package is **`memora-mcp`** (bare `memora` on PyPI is an unrelated project). Includes cloud storage (S3/R2) and OpenAI embeddings out of the box.
  81. ```bash
  82. # Optional: local embeddings (offline, ~2GB for PyTorch)
  83. pip install "memora-mcp[local]"
  84. # Latest development version straight from git
  85. pip install "git+https://github.com/agentic-box/memora.git"
  86. ```
  87. Then spawn it from `.mcp.json` with `"command": "memora-server"` (see [Configuration](#configuration)).
  88. ### Container (HTTP service)
  89. Default runtime is Apple's [`container`](https://github.com/apple/container) CLI. Every container operation `scripts/memora-instance.sh` performs (`build`, `up`, `status`, `logs`, `down`) uses `$MEMORA_CONTAINER_BIN` (default `container`). The generated proxy process does not; it hardcodes `container list`.
  90. **Before the first `build`:**
  91. 1. Install Apple's `container` CLI (signed pkg from its GitHub releases). It needs a Mac with Apple silicon **running macOS 26** — Apple does not support older macOS versions for `container`.
  92. 2. Start the runtime — Apple's documented first command, which also installs a kernel if none is configured:
  93. ```bash
  94. container system start
  95. ```
  96. 3. Clone this repo and `cd` into it:
  97. ```bash
  98. git clone https://github.com/agentic-box/memora.git
  99. cd memora
  100. ```
  101. 4. Copy the instance template. It ships with `INSTANCE=myinstance` so the later `build`/`up`/`proxy` lines match without renaming. Edit `PORT` and a backend (`STORAGE_URI`, `VOLUME`, or `MEMORA_DATABASES`):
  102. ```bash
  103. cp instances/example.env instances/myinstance.env
  104. ```
  105. 5. Create the credential file and install the proxy the LaunchAgent will run. `cred_args()` requires a `.mcp.json` whose `mcpServers.memora.env` holds `CLOUDFLARE_API_TOKEN` (D1 access) and the embedding/LLM keys — `up` dies if that file is missing. The script looks for `~/.config/memora/credentials.mcp.json` unless the instance file sets `CRED_SOURCE` to another path; there is no other fallback. Separately, `proxy` renders a plist whose executable is `$MEMORA_PROXY_BIN` (default `~/.local/libexec/memora/memora_proxy.py`) and whose logs live in `$MEMORA_LOG_DIR` (default `~/.local/var/log`) — nothing creates either on a fresh clone.
  106. ```bash
  107. mkdir -p ~/.config/memora ~/.local/libexec/memora ~/.local/var/log
  108. cp scripts/memora_proxy.py ~/.local/libexec/memora/
  109. # real values; any key is fine, an absent file is not
  110. # the default umask is permissive -- chmod 600 keeps other local accounts out
  111. cat > ~/.config/memora/credentials.mcp.json <<'JSON'
  112. {"mcpServers":{"memora":{"env":{"CLOUDFLARE_API_TOKEN":"REPLACE","OPENAI_API_KEY":"REPLACE"}}}}
  113. JSON
  114. chmod 600 ~/.config/memora/credentials.mcp.json
  115. ```
  116. That JSON is the minimal correct config: both the LLM and embeddings use the
  117. default OpenAI host with a real OpenAI key. Do **not** add
  118. `OPENAI_BASE_URL` pointing at OpenRouter without the embedding pair from
  119. [Embeddings](#semantic-search--embeddings) — OpenRouter has no embeddings
  120. endpoint, every embed call 404s, and memora silently falls back to TF-IDF
  121. keyword bags while looking healthy.
  122. Then:
  123. ```bash
  124. ./scripts/memora-instance.sh build myinstance # tags IMAGE from myinstance.env (memora-pilot if IMAGE is unset)
  125. ./scripts/memora-instance.sh up myinstance # runs that same IMAGE
  126. ./scripts/memora-instance.sh proxy myinstance # render the LaunchAgent; run the printed launchctl
  127. ```
  128. `up` does **not** publish a host port. The listener the workspace connects to is the proxy. `proxy` only *renders* a macOS LaunchAgent and prints the `launchctl` commands — it does not load the service. Run those printed commands.
  129. The printed workspace URL is always `http://127.0.0.1:<PORT>/mcp` (the registry default). For a non-default store, append `/<name>` yourself — a bare `/mcp` on a registry silently binds `MEMORA_DEFAULT_DB`:
  130. ```json
  131. {"mcpServers": {"memora": {"type": "http", "url": "http://127.0.0.1:<PORT>/mcp/<store>"}}}
  132. ```
  133. Proxy rationale, credentials, instance files, and `MEMORA_CONTAINER_BIN`: [Container Deployment](#container-deployment).
  134. <details id="usage">
  135. <summary><big><big><strong>Usage</strong></big></big></summary>
  136. The server runs automatically when configured in Claude Code. Manual invocation:
  137. ```bash
  138. # Default (stdio mode for MCP)
  139. memora-server
  140. # With graph visualization server
  141. memora-server --graph-port 8765
  142. # HTTP transport (alternative to stdio)
  143. memora-server --transport streamable-http --host 127.0.0.1 --port 8080
  144. ```
  145. </details>
  146. <details id="configuration">
  147. <summary><big><big><strong>Configuration</strong></big></big></summary>
  148. ### Claude Code
  149. Add to `.mcp.json` in your project root:
  150. **Local DB:**
  151. ```json
  152. {
  153. "mcpServers": {
  154. "memora": {
  155. "command": "memora-server",
  156. "args": [],
  157. "env": {
  158. "MEMORA_DB_PATH": "~/.local/share/memora/memories.db",
  159. "MEMORA_ALLOW_ANY_TAG": "1",
  160. "MEMORA_GRAPH_PORT": "8765"
  161. }
  162. }
  163. }
  164. }
  165. ```
  166. **Cloud DB (Cloudflare D1) - Recommended:**
  167. ```json
  168. {
  169. "mcpServers": {
  170. "memora": {
  171. "command": "memora-server",
  172. "args": ["--no-graph"],
  173. "env": {
  174. "MEMORA_STORAGE_URI": "d1://<account-id>/<database-id>",
  175. "CLOUDFLARE_API_TOKEN": "<your-api-token>",
  176. "MEMORA_ALLOW_ANY_TAG": "1"
  177. }
  178. }
  179. }
  180. }
  181. ```
  182. With D1, use `--no-graph` to disable the local visualization server. Instead, use the hosted graph at your Cloudflare Pages URL (see [Cloud Graph](#cloud-graph)).
  183. A `d1://` primary refuses to start unless that database's read replication is disabled (session bookmarks are not REST read-your-writes while it is on). `MEMORA_D1_ALLOW_READ_REPLICATION=1` starts anyway and logs a warning.
  184. **Cloud DB (S3/R2) - Sync mode:**
  185. ```json
  186. {
  187. "mcpServers": {
  188. "memora": {
  189. "command": "memora-server",
  190. "args": [],
  191. "env": {
  192. "AWS_PROFILE": "memora",
  193. "AWS_ENDPOINT_URL": "https://<account-id>.r2.cloudflarestorage.com",
  194. "MEMORA_STORAGE_URI": "s3://memories/memories.db",
  195. "MEMORA_CLOUD_ENCRYPT": "true",
  196. "MEMORA_ALLOW_ANY_TAG": "1",
  197. "MEMORA_GRAPH_PORT": "8765"
  198. }
  199. }
  200. }
  201. }
  202. ```
  203. ### Codex CLI
  204. Add to `~/.codex/config.toml`:
  205. ```toml
  206. [mcp_servers.memora]
  207. command = "memora-server" # or full path: /path/to/bin/memora-server
  208. args = ["--no-graph"]
  209. env = {
  210. AWS_PROFILE = "memora",
  211. AWS_ENDPOINT_URL = "https://<account-id>.r2.cloudflarestorage.com",
  212. MEMORA_STORAGE_URI = "s3://memories/memories.db",
  213. MEMORA_CLOUD_ENCRYPT = "true",
  214. MEMORA_ALLOW_ANY_TAG = "1",
  215. }
  216. ```
  217. </details>
  218. <details id="environment-variables">
  219. <summary><big><big><strong>Environment Variables</strong></big></big></summary>
  220. | Variable | Description |
  221. |------------------------|-----------------------------------------------------------------------------|
  222. | `MEMORA_DB_PATH` | Local SQLite database path (default: `~/.local/share/memora/memories.db`) |
  223. | `MEMORA_STORAGE_URI` | Storage URI: `d1://<account>/<db-id>` (D1) or `s3://bucket/memories.db` (S3/R2). Used when `MEMORA_DATABASES` is unset. |
  224. | `MEMORA_DATABASES` | JSON object `{name: uri}` mapping each store this process serves. Names are one URL path segment (`/mcp/<name>`): letters, digits, `-`, `_`, `.` only. Duplicate keys, empty values, unsafe names, or non-objects refuse to start rather than silently picking a store. Unset = single-store (legacy). See [Multi-database routing](#multi-database-routing). |
  225. | `MEMORA_DEFAULT_DB` | Registry name a bare `/mcp` uses. Required when the registry has more than one database; with exactly one name, that name is the default. A value not in the registry refuses to start. |
  226. | `CLOUDFLARE_API_TOKEN` | API token for D1 (`d1://` URI). `CF_API_TOKEN` is accepted as an alias. |
  227. | `MEMORA_D1_ALLOW_READ_REPLICATION` | Set to `1` to start a `d1://` primary when read replication is on, or when its mode cannot be read. Any other value still refuses. Logs a warning on every start. |
  228. | `MEMORA_CLOUD_ENCRYPT` | Encrypt the local file before uploading to S3/R2. Unset/`false` = off; `1`/`true`/`yes` = on. |
  229. | `MEMORA_CLOUD_COMPRESS`| Compress the local file before uploading to S3/R2. Unset/`false` = off; `1`/`true`/`yes` = on. |
  230. | `MEMORA_CACHE_DIR` | Local cache directory for an S3/R2-synced database. Unset: the backend picks a cache path. |
  231. | `MEMORA_ALLOW_ANY_TAG` | Allow any tag without validation against allowlist (`1` to enable) |
  232. | `MEMORA_TAG_FILE` | Path to a JSON file containing an array of allowed tags, e.g. `["plan", "memora/issues"]` |
  233. | `MEMORA_TAGS` | Comma-separated list of allowed tags |
  234. | `MEMORA_HOST` | Bind address for HTTP transports (default `127.0.0.1`). Overridable with `--host`. |
  235. | `MEMORA_PORT` | Bind port for HTTP transports (default `8000`). Overridable with `--port`. |
  236. | `MEMORA_GRAPH_PORT` | Port for the knowledge graph visualization server (default: `8765`) |
  237. | `MEMORA_TRANSPORT` | `stdio` (default), `sse`, or `streamable-http`. An unknown **env** value falls back to `stdio`; `--transport` still rejects unknown values. Multi-database routing and the session guard run only on `streamable-http`. |
  238. | `MEMORA_TOOL_PROFILE` | Tool subset exposed to clients: `full` (default, all 44), `leader` (19), `agent` (12). Unset/empty = `full`; an unknown value refuses to start. See [Tool Profiles](#tool-profiles). |
  239. | `MEMORA_MAX_SESSIONS` | Hard ceiling on concurrent MCP sessions (default `128`). `0` disables. A creation rate plus an idle timeout is not a bound — a client that keeps session ids alive can grow without limit at the creation rate. Invalid values refuse to start. Streamable-HTTP only. |
  240. | `MEMORA_MAX_INIT_PER_MIN` | New sessions admitted per minute (default `120`). `0` disables. Invalid values refuse to start. Streamable-HTTP only. |
  241. | `MEMORA_MAX_INIT_BODY_BYTES` | Maximum initialize request body accepted/buffered (default `65536`, minimum `1024`). Larger requests receive `413`. Invalid values refuse to start. Streamable-HTTP only. |
  242. | `MEMORA_SESSION_IDLE_TIMEOUT` | Seconds before an abandoned valid session is reaped (default `1800`). `0` disables. Invalid values refuse to start. Streamable-HTTP only. |
  243. | `MEMORA_HEALTH_TOKEN` | Bearer token for detailed `/health/db` bodies (names, counts, error text). Unset: only a loopback peer sees detail; everyone else gets aggregate status. FastMCP `custom_route()` is unauthenticated even when MCP auth is configured. HTTP transports only (`memora.health` is imported for SSE/streamable-http, not stdio). |
  244. | `MEMORA_ADMIN_TOKEN` | Bearer token for the `/admin/*` operator routes (`memora/admin.py`), at least 32 characters and different from `MEMORA_HEALTH_TOKEN`; otherwise the server refuses to start. Unset: every `/admin/*` route answers 403. No loopback exemption. The instance launchers mint and pass it (`~/.config/memora/<instance>.admin-token`). HTTP transports only. |
  245. | `MEMORA_DATA_VOLUME` | Name of the volume mounted at `/data`, set by the launchers. A store that keeps state in the data directory (`MEMORA_DATA_DIR`, default `/data`: a local SQLite path under it, and every `d1://` store, whose write gate and intent journal live there) is refused unless this is set and not an anonymous 64-hex volume id, the directory is a mount point, and a probe file can be written, fsynced and removed in it and in its `intent/`. The refusal is per store; `/health/db` names the reason. |
  246. | `MEMORA_HEALTH_TTL` | Seconds a readiness snapshot may be served before a refresh is due (default `10`, cap `3600`). Must be `> 0`. Invalid values refuse to start. HTTP transports only — a malformed value does not abort stdio. |
  247. | `MEMORA_HEALTH_TIMEOUT`| Bound on one refresh pass and on each store probe (default `15`, cap `300`). Must be `> 0`. HTTP transports only. |
  248. | `MEMORA_HEALTH_REFRESH_INTERVAL` | How often the server refreshes readiness on its own (default `15`, cap `3600`). `0` = poll-only. Without this, a proxy deployment has no loopback caller and the alert surface stays `unknown` while every database is fine. When periodic refresh is enabled, `interval + timeout` must be `< MEMORA_HEALTH_MAX_STALE`. HTTP transports only. |
  249. | `MEMORA_HEALTH_MAX_STALE` | Age after which a cached per-database result may no longer be reported ready (default `60`, cap `3600`). Must be `>= MEMORA_HEALTH_TTL`. HTTP transports only. |
  250. | `MEMORA_STALE_DAYS` | Two consumers, two defaults, same name: `memory_insights` treats an open TODO/issue as stale after **14** days; the graph UI greys closed items after **30** days. Set the variable to override both. |
  251. | `MEMORA_EMBEDDING_MODEL` | Embedding backend: `openai` (default), `sentence-transformers`, or `tfidf` |
  252. | `SENTENCE_TRANSFORMERS_MODEL` | Model for sentence-transformers (default: `all-MiniLM-L6-v2`) |
  253. | `MEMORA_EMBEDDING_API_KEY` | Embedding provider API key (atomic with base URL — see below) |
  254. | `MEMORA_EMBEDDING_BASE_URL` | Embedding provider base URL (atomic with API key — see below) |
  255. | `MEMORA_EMBEDDING_STRICT` | **Recommend `1`.** Fail hard on embedding errors instead of silent TF-IDF. Without it a broken endpoint keeps answering while every vector becomes a keyword bag (how 756 memories degraded unnoticed). |
  256. | `OPENAI_API_KEY` | **LLM only** (dedup/chat) when `MEMORA_EMBEDDING_*` is set. Embeddings fall back to this key only if **both** `MEMORA_EMBEDDING_API_KEY` and `MEMORA_EMBEDDING_BASE_URL` are unset |
  257. | `OPENAI_BASE_URL` | **LLM** base URL (OpenRouter, Azure, etc.). Same atomic fallback rule as the key — not an embeddings URL when you use a split config |
  258. | `OPENAI_EMBEDDING_MODEL` | Model id for the openai embedding backend. Must exist on the **embedding** host (default `text-embedding-3-small` is OpenAI-only; Cloudflare needs e.g. `@cf/baai/bge-m3`) |
  259. | `MEMORA_LLM_ENABLED` | Enable LLM-powered deduplication comparison (`true`/`1`/`yes`; default: `true`) |
  260. | `MEMORA_LLM_MODEL` | Model for deduplication comparison and, if unset, for query rewrite and local chat (default: `gpt-4o-mini`). Pick a plain chat/instruct model, not a reasoning model — a reasoning model was measured at 12-17s per absorb classification call (1000-1700 reasoning tokens it does not let OpenRouter's `reasoning.effort`/`reasoning.max_tokens` bound), vs 3-4s for `gpt-4o-mini` on the same calls. |
  261. | `MEMORA_ABSORB_CONCURRENCY` | Worker count for `memory_absorb`'s concurrent classify phase (default `4`; non-numeric or `<1` falls back to `4`; `1` disables the thread pool and classifies sequentially). Only the per-fact LLM classification call is parallelized — embeds and searches stay sequential (cheap, and `conn` isn't safe to touch from worker threads: sqlite3 connections are thread-affine by default and `D1Connection` carries mutable session-token state). |
  262. | `MEMORA_LLM_TIMEOUT` | Seconds the OpenAI client waits (default `60`, floored at `1`). A non-numeric value falls back to `60`. |
  263. | `MEMORA_REWRITE_MODEL` | Model for RAG query rewriting in the graph chat panel. Unset/empty uses `MEMORA_LLM_MODEL`. |
  264. | `MEMORA_VECTOR_SCAN_PAGE_SIZE` | Rows per page when loading embeddings from D1 (default `1000`; non-numeric or `<1` falls back to `1000`; hard ceiling `10000`). At the default, a store under 1000 rows returns the **entire corpus plus every embedding in one D1 response**, which raced Cloudflare's 30s per-request ceiling and made `memory_absorb` fail outright. **Use `100` on D1** (the instance script already injects that). Paging is a mitigation, not the fix: absorb reads the corpus once per call and reuses a process-local cache keyed on the DB's monotonic `embedding_change_epoch`. |
  265. | `MEMORA_REBUILD_CHUNK_SIZE` | Rows per batch in `memory_rebuild_embeddings` (default `32`; non-numeric or `<1` falls back to `32`). Each batch is one `compute_embeddings_batch` call and one `conn.commit()`, instead of one embed call and one commit per row — on D1 this collapses the lease-heartbeat round trips from two per row to two per batch, which dominated wall time far more than the per-row commits did (D1's `commit()` is already a no-op). |
  266. | `CHAT_MODEL` | Model for the local graph chat panel. Unset/empty falls back to `MEMORA_LLM_MODEL`. (The `deepseek/deepseek-chat` default is Cloudflare Pages `wrangler.toml`, not this process.) |
  267. | `MEMORA_CLOUD_GRAPH_ENABLED` | `true`/`1`/`yes` to notify the hosted graph of writes (default off). |
  268. | `MEMORA_CLOUD_GRAPH_WORKER_URL` | Worker base URL for those broadcasts (`POST <url>/broadcast`). Unset: broadcasts are skipped. |
  269. | `MEMORA_CLOUD_GRAPH_DEBOUNCE` | Seconds to batch rapid writes before broadcasting (default `1.0`). |
  270. | `MEMORA_CLOUD_GRAPH_SYNC_SCRIPT` | Path captured at startup (default: `memora-graph/scripts/sync.sh` if that file exists). The current write path does **not** execute this script — D1 is the source of truth and only the worker broadcast runs. |
  271. | `AWS_PROFILE` | AWS credentials profile from `~/.aws/credentials` (useful for R2) |
  272. | `AWS_ENDPOINT_URL` | S3-compatible endpoint for R2/MinIO |
  273. | `R2_PUBLIC_DOMAIN` | Public domain for R2 image URLs |
  274. </details>
  275. <details id="tool-profiles">
  276. <summary><big><big><strong>Tool Profiles (MEMORA_TOOL_PROFILE)</strong></big></big></summary>
  277. All 44 MCP tools register unconditionally, so every agent session is injected with the full ~12,700-token tool schema even when most tools are never called. `MEMORA_TOOL_PROFILE` exposes a subset per deployment so a gated tool is **genuinely absent** — missing from `tools/list` AND undispatchable (`call_tool` returns `unknown-tool`, not a hidden execution). The profile is applied and attested at startup; the active profile and exposed tool count are logged to stderr.
  278. | Value | Tools | Use |
  279. |-------|-------|-----|
  280. | `full` (default) | all 44 | Direct stdio use; every existing deployment is byte-for-byte unchanged |
  281. | `leader` | 19 | The agent set plus `memory_create_section`, `memory_store_document`, `memory_get_document`, `memory_tags`, `memory_delete`, `memory_digest`, `memory_list` |
  282. | `agent` | 12 | The read/create surface a worker agent needs: `memory_absorb`, `memory_semantic_search`, `memory_hybrid_search`, `memory_list_compact`, `memory_get`, `memory_related`, `memory_link`, `memory_stats`, `memory_create`, `memory_create_issue`, `memory_create_todo`, `memory_update` |
  283. - **Unset / empty = `full`.** No existing deployment changes behaviour.
  284. - **An unknown value aborts startup** with a message naming the valid values. It never silently falls back to `full` — a typo must not re-expose destructive maintenance tools (`memory_rebuild_embeddings`, `memory_delete_batch`) to every worker. Fail closed.
  285. - `memory_list` is in `leader` but not `agent`. It was excluded from both while it cost 163-174s on a D1 store against `memory_list_compact`'s 0.22s; #973 fixed that (now ~1.1s). It stays out of `agent` because a worker's read surface is deliberately narrow, not for speed.
  286. - The leader/agent boundary is **data** in `memora/tool_profile.py` (two frozensets). Editing it is one line, not a sweep of 44 decorators.
  287. - The prune deletes from FastMCP's private `_tool_manager._tools` dict, so `memora` pins `mcp>=1.27,<1.28` (the audited minor) and runs a startup **attestation** through the low-level registered MCP request handlers (`_mcp_server.request_handlers[ListToolsRequest]` / `[CallToolRequest]` — the actual dispatch callable real client requests use, not the `FastMCP.list_tools` / `call_tool` Python helpers) that refuses to start if the installed SDK routes listing/dispatch elsewhere (private-implementation drift). The pin is the static guard; the attestation is the runtime backstop. Bumping the upper bound requires re-running `tests/test_tool_profile.py`.
  288. - Under [container deployment](#container-deployment) the profile is per *container* while roles are per *agent*. One container serving a workspace's leader and its workers needs the **leader** superset; `agent` would strip `create_section`/`store_document`/`delete`/`digest`/`tags` from the leader.
  289. - `memora-server` (i.e. `memora.server.main()`) is the sole supported **profiled** serving path. A direct embedder that imports `memora.server.mcp` and calls `mcp.run()` themselves bypasses profiling entirely (the global `mcp` still holds all 44 tools); embedders who want profiling must call `apply_tool_profile` themselves or use `main()`.
  290. ```bash
  291. # Leader deployment — exposes 19 tools
  292. MEMORA_TOOL_PROFILE=leader memora-server
  293. # Agent worker — exposes 12 tools
  294. MEMORA_TOOL_PROFILE=agent memora-server
  295. # Full (default) — all 44 tools, existing behaviour
  296. memora-server
  297. # Typo refuses to start:
  298. # MEMORA_TOOL_PROFILE=agnt memora-server
  299. # Error: unknown MEMORA_TOOL_PROFILE='agnt'; valid values: full, leader, agent
  300. ```
  301. </details>
  302. <details id="multi-database-routing">
  303. <summary><big><big><strong>Multi-database routing</strong></big></big></summary>
  304. One memora process can serve every workspace. `MEMORA_DATABASES` is a JSON
  305. registry of `{name: storage URI}`; a client reaches its store at `/mcp/<name>`.
  306. The selector is the URL already in `.mcp.json`, not a tool argument — an optional
  307. `db` on every tool is 44 chances to forget one, and every miss would write into
  308. someone else's store.
  309. **Unset `MEMORA_DATABASES` is the old shape:** one backend from `MEMORA_STORAGE_URI`
  310. / `MEMORA_DB_PATH`, one `/mcp`. Existing stdio deployments do not change.
  311. **Routing (streamable-http only):**
  312. | URL | Resolves to |
  313. |-----|-------------|
  314. | `/mcp/<name>` | That registry entry. Unknown names return `404 {"error":"unknown database"}` — the body does not list the other names. |
  315. | `/mcp` | `MEMORA_DEFAULT_DB`. Required when the registry has more than one database; a single-name registry uses that name. |
  316. The binding is **sticky per MCP session**, not per request. A session opened on
  317. `/mcp/alpha` and reused against `/mcp/beta` still resolves to `alpha`. A client
  318. cannot half-switch databases mid-conversation.
  319. Malformed configuration **refuses to start** (it does not fall through to the
  320. legacy database): bad JSON, a non-object, duplicate keys, an empty URI, a name
  321. that is not one URL path segment, or `MEMORA_DEFAULT_DB` missing/unknown when
  322. more than one database is listed.
  323. **Worked pair — run this, connect to this.** A streamable-HTTP listener, not
  324. an MCP `command` entry (that would spawn a stdio child that never speaks MCP
  325. on stdio). Credentials live on the server process.
  326. ```bash
  327. MEMORA_DATABASES='{"memora":"d1://<account-id>/<memora-db-id>","alpha":"d1://<account-id>/<alpha-db-id>"}' \
  328. MEMORA_DEFAULT_DB=memora \
  329. CLOUDFLARE_API_TOKEN='<token>' \
  330. MEMORA_VECTOR_SCAN_PAGE_SIZE=100 \
  331. memora-server --transport streamable-http --host 127.0.0.1 --port 8000 --no-graph
  332. ```
  333. ```json
  334. {
  335. "mcpServers": {
  336. "memora": {
  337. "type": "http",
  338. "url": "http://127.0.0.1:8000/mcp/alpha"
  339. }
  340. }
  341. }
  342. ```
  343. **Container / proxy variant** (this host's usual launcher, not the command
  344. above): `scripts/memora-instance.sh up myinstance` starts the same HTTP server
  345. inside a container and puts `scripts/memora_proxy.py` on `127.0.0.1:<PORT>`
  346. (8910 for the `memora` instance). The workspace URL is then
  347. `http://127.0.0.1:8910/mcp/alpha`. See [Container Deployment](#container-deployment).
  348. A registry may mix `d1://`, `s3://`, and local paths; `parse_backend_uri`
  349. dispatches on the scheme.
  350. **`memory_stats` reports the bound database.** It returns `database` (the name
  351. this session actually resolved) and `database_source` (`path`,
  352. `registry_default`, or `unconfigured`). A valid-but-wrong name in `.mcp.json`
  353. is otherwise undetectable: every tool works, reads succeed, and writes land
  354. silently in another project's store. Call `memory_stats` and check `database`
  355. against the workspace you meant.
  356. Health of a multi-database process: `GET /health` is liveness (no database I/O
  357. — the only signal a supervisor may restart on). `GET /health/db` is an alert
  358. surface (always HTTP 200; `status` is `ok`, `degraded`, `unknown` — no
  359. snapshot yet, a refresh timed out, or evidence older than max staleness — or
  360. `error` if the registry itself is unusable). `GET /health/db/{name}` is the
  361. workspace-specific probe (200 or 503). Withdrawing the whole process because
  362. one store is degraded takes the healthy ones down with it.
  363. </details>
  364. <details id="container-deployment">
  365. <summary><big><big><strong>Container Deployment</strong></big></big></summary>
  366. With `MEMORA_DATABASES` unset, a process still binds **one** database for its
  367. lifetime (`MEMORA_STORAGE_URI` / `MEMORA_DB_PATH`). That is the original
  368. one-store-one-container-one-port shape.
  369. With `MEMORA_DATABASES` set, **one container serves every workspace** and
  370. clients select a store by URL path (`/mcp/<name>`). See
  371. [Multi-database routing](#multi-database-routing). `scripts/memora-instance.sh`
  372. wants one of `STORAGE_URI`, `VOLUME`, or `MEMORA_DATABASES` per instance file
  373. (`load()` requires at least one). If more than one is set, `cmd_up` uses
  374. `MEMORA_DATABASES`, then `STORAGE_URI`, then `VOLUME`.
  375. `Dockerfile` builds a credential-free image; `scripts/memora-instance.sh` deploys one
  376. instance from `instances/myinstance.env` (or another named file). The script's runtime CLI is
  377. `$MEMORA_CONTAINER_BIN` (default `container` — Apple's CLI). Every container
  378. operation the script performs honours that override (`build`, `up`, `status`,
  379. `logs`, `down`). The generated `memora_proxy.py` process hardcodes
  380. `container list`, which is also why the proxy exists: that runtime reassigns
  381. the container's IP on every start.
  382. ```bash
  383. ./scripts/memora-instance.sh build myinstance # build the image
  384. ./scripts/memora-instance.sh up myinstance # run the container
  385. ./scripts/memora-instance.sh proxy myinstance # render a LaunchAgent + print install commands
  386. ./scripts/memora-instance.sh status # every instance at a glance
  387. ```
  388. Then point the workspace at it — the whole client config, with no secrets in it.
  389. A registry instance needs the store in the path (`/mcp/<name>`); bare `/mcp` is
  390. the registry default:
  391. ```json
  392. {"mcpServers": {"memora": {"type": "http", "url": "http://127.0.0.1:8910/mcp/alpha"}}}
  393. ```
  394. **Credentials never enter the image, the instance file, or the workspace's HTTP
  395. config.** They are read at run time from a separate credential config
  396. (`$CRED_SOURCE` — itself a `.mcp.json` holding only the `mcpServers.memora.env`
  397. block) and injected with `-e`. If the instance file does not set
  398. `CRED_SOURCE`, the script uses `~/.config/memora/credentials.mcp.json` (and `up`
  399. refuses when it is missing; there is no other fallback). Pass through *every*
  400. variable that file defines, not a hand-picked few: a container started with only
  401. the embedding keys silently loses `memory_absorb`'s LLM consolidation instead of
  402. failing loudly.
  403. **Why the proxy exists — read this before deciding you do not need it.** The
  404. default runtime (Apple's `container`) reassigns a container's IP on *every start*, not just on recreate.
  405. An MCP client reads its config once at startup, so a moved address does not produce an
  406. error: it produces a permanent silent hang. `scripts/memora_proxy.py` holds a stable
  407. `127.0.0.1:<PORT>` in front of the moving address and re-resolves per connection.
  408. Two failure modes it distinguishes, which cost an outage to learn:
  409. - The lookup **ran** and the container is not listed → it really is gone. Refuse.
  410. - The lookup **could not run** (timeout under host memory pressure) → nothing new is
  411. known. Keep serving the last known good address, bounded by `MEMORA_PROXY_STALE_GRACE`
  412. (300s). Conflating the two took every workspace offline while the containers were
  413. answering normally on unchanged addresses.
  414. Set `MEMORA_TOOL_PROFILE` per instance (see **Tool Profiles**). Note the profile is
  415. per *container* while roles are per *agent*: if one container serves a workspace's
  416. leader and its workers, it needs the leader superset.
  417. Deploy-time script variable (not a memora-server env var — it never reaches
  418. the process inside the container):
  419. | Variable | Meaning |
  420. |----------|---------|
  421. | `MEMORA_CONTAINER_BIN` | CLI every `memora-instance.sh` container operation uses (`build`, `up`, `status`, `logs`, `down`; default `container`). The generated `memora_proxy.py` process does not honour this; it hardcodes `container list`. |
  422. `instances/README.md` covers the config fields and `launchd/README.md` the supervised
  423. proxy. `REVERT.md` documents restoring a workspace to the direct stdio server.
  424. </details>
  425. <details id="semantic-search--embeddings">
  426. <summary><big><big><strong>Semantic Search & Embeddings</strong></big></big></summary>
  427. Memora supports three embedding backends:
  428. | Backend | Install | Quality | Speed |
  429. |---------|---------|---------|-------|
  430. | `openai` (default) | Included | High quality | API latency |
  431. | `sentence-transformers` | `pip install memora[local]` | Good, runs offline | Medium |
  432. | `tfidf` | Included | Basic keyword matching | Fast |
  433. **Embeddings and the LLM are configured separately.**
  434. | Role | Variables |
  435. |------|-----------|
  436. | LLM (dedup, chat) | `OPENAI_API_KEY` + `OPENAI_BASE_URL` |
  437. | Embeddings | `MEMORA_EMBEDDING_API_KEY` + `MEMORA_EMBEDDING_BASE_URL` (**both or neither** — atomic pair) |
  438. | Fallback | If **both** `MEMORA_EMBEDDING_*` are unset, embeddings use the full `OPENAI_*` pair |
  439. A partial split (only one `MEMORA_EMBEDDING_*` set) is **rejected** so one provider’s secret is never sent to another host.
  440. **Trap — OpenRouter has no embeddings endpoint.** OpenRouter’s catalogue is chat/multimodal only (no embedding models). Do **not** point the embedding path at OpenRouter via `OPENAI_BASE_URL` (or a MEMORA base URL). That combination 404s every embed call; without `MEMORA_EMBEDDING_STRICT=1` Memora falls back to TF-IDF and keeps answering, so the store fills with keyword bags while looking healthy. OpenRouter remains fine for the **LLM** only.
  441. **Worked example (LLM via OpenRouter, embeddings via Cloudflare Workers AI):**
  442. `@cf/baai/bge-m3` is 1024-dimensional. Token needs Workers AI permission. Endpoint shape:
  443. `https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1`
  444. ```json
  445. {
  446. "env": {
  447. "MEMORA_EMBEDDING_MODEL": "openai",
  448. "OPENAI_API_KEY": "<openrouter-key>",
  449. "OPENAI_BASE_URL": "https://openrouter.ai/api/v1",
  450. "MEMORA_LLM_MODEL": "deepseek/deepseek-chat",
  451. "MEMORA_EMBEDDING_API_KEY": "<cloudflare-api-token-with-workers-ai>",
  452. "MEMORA_EMBEDDING_BASE_URL": "https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1",
  453. "OPENAI_EMBEDDING_MODEL": "@cf/baai/bge-m3",
  454. "MEMORA_EMBEDDING_STRICT": "1"
  455. }
  456. }
  457. ```
  458. What this fix does (no oversell): embeddings and LLM can use different providers; a partial split is rejected; strict mode turns silent degradation into a hard, named failure.
  459. **Automatic:** Embeddings and cross-references are computed automatically when you `memory_create`, `memory_update`, or `memory_create_batch`.
  460. **Manual rebuild required** when the store fingerprint changes — not only `MEMORA_EMBEDDING_MODEL`, but also:
  461. - Embedding **endpoint** (`MEMORA_EMBEDDING_BASE_URL` / host)
  462. - Actual model id (`OPENAI_EMBEDDING_MODEL`, e.g. switching to `@cf/baai/bge-m3`)
  463. - Vector **kind or dimensions** (word-key TF-IDF bags vs dense 1024-d; or 384 vs 1024)
  464. - Mixed store (some rows dense, some sparse) — cosine similarity only shares keys, so mixed kinds yield **0.0** recall for old rows
  465. Fingerprint form: `backend|model|repr` (e.g. `openai|@cf/baai/bge-m3|dense:1024`). Legacy meta value `openai` alone is treated as a mismatch.
  466. ```bash
  467. # After changing embedding model/endpoint, rebuild all embeddings
  468. memory_rebuild_embeddings
  469. # Then rebuild cross-references to update the knowledge graph
  470. memory_rebuild_crossrefs
  471. ```
  472. </details>
  473. <details id="live-graph-server">
  474. <summary><big><big><strong>Live Graph Server</strong></big></big></summary>
  475. A built-in HTTP server starts automatically with the MCP server, serving an interactive knowledge graph visualization.
  476. <table>
  477. <tr>
  478. <td align="center"><img src="media/ui_details.png" alt="Details Panel" width="400"><br><em>Details Panel</em></td>
  479. <td align="center"><img src="media/ui_timeline.png" alt="Timeline Panel" width="400"><br><em>Timeline Panel</em></td>
  480. </tr>
  481. </table>
  482. **Access locally:**
  483. ```
  484. http://localhost:8765/graph
  485. ```
  486. **Remote access via SSH:**
  487. ```bash
  488. ssh -L 8765:localhost:8765 user@remote
  489. # Then open http://localhost:8765/graph in your browser
  490. ```
  491. **Configuration:**
  492. ```json
  493. {
  494. "env": {
  495. "MEMORA_GRAPH_PORT": "8765"
  496. }
  497. }
  498. ```
  499. To disable: add `"--no-graph"` to args in your MCP config.
  500. ### Graph UI Features
  501. - **Details Panel** - View memory content, metadata, tags, and related memories
  502. - **Timeline Panel** - Browse memories chronologically, click to highlight in graph
  503. - **History Panel** - Action log of all operations with grouped consecutive entries and clickable memory references (deleted memories shown as strikethrough)
  504. - **Chat Panel** - Ask questions about your memories using RAG-powered LLM chat with streaming responses and clickable `[Memory #ID]` references
  505. - **Time Slider** - Filter memories by date range, drag to explore history
  506. - **Real-time Updates** - Graph, timeline, and history update via SSE when memories change
  507. - **Filters** - Tag/section dropdowns, zoom controls
  508. - **Mermaid Rendering** - Code blocks render as diagrams
  509. ### Node Colors
  510. - 🟣 **Tags** - Purple shades by tag
  511. - 🔴 **Issues** - Red (open), Orange (in progress), Green (resolved), Gray (won't fix)
  512. - 🔵 **TODOs** - Blue (open), Orange (in progress), Green (completed), Red (blocked)
  513. Node size reflects connection count.
  514. </details>
  515. <details id="cloud-graph">
  516. <summary><big><big><strong>Cloud Graph (Recommended for D1)</strong></big></big></summary>
  517. When using Cloudflare D1 as your database, the graph visualization is hosted on Cloudflare Pages - no local server needed.
  518. **Benefits:**
  519. - Access from anywhere (no SSH tunneling)
  520. - Real-time updates via WebSocket
  521. - Multi-database support via `?db=` parameter
  522. - Secure access with Cloudflare Zero Trust
  523. **Setup:**
  524. 1. **Create D1 database:**
  525. ```bash
  526. npx wrangler d1 create memora-graph
  527. npx wrangler d1 execute memora-graph --file=memora-graph/schema.sql
  528. ```
  529. 2. **Deploy Pages:**
  530. ```bash
  531. cd memora-graph
  532. npm run deploy
  533. ```
  534. `npm run deploy` runs `scripts/d1_write_guard.py --scope all` first and refuses on any finding. Do not run `wrangler pages deploy` directly: it bypasses the guard (`docs/local-primary-implementation.md` §0 P6).
  535. 3. **Configure bindings** in Cloudflare Dashboard:
  536. - Pages → memora-graph → Settings → Bindings
  537. - Add D1: `DB_MEMORA` → your database
  538. - Add R2: `R2_MEMORA` → your bucket (for images)
  539. 4. **Configure MCP** with D1 URI:
  540. ```json
  541. {
  542. "env": {
  543. "MEMORA_STORAGE_URI": "d1://<account-id>/<database-id>",
  544. "CLOUDFLARE_API_TOKEN": "<your-token>"
  545. }
  546. }
  547. ```
  548. **Access:** `https://memora-graph.pages.dev`
  549. **Secure with Zero Trust:**
  550. 1. Cloudflare Dashboard → Zero Trust → Access → Applications
  551. 2. Add application for `memora-graph.pages.dev`
  552. 3. Create policy with allowed emails
  553. 4. Pages → Settings → Enable Access Policy
  554. See [`memora-graph/`](memora-graph/) for detailed setup and multi-database configuration.
  555. </details>
  556. <details id="chat-with-memories">
  557. <summary><big><big><strong>Chat with Memories</strong></big></big></summary>
  558. Ask questions about your knowledge base directly from the graph UI. The chat panel uses RAG (Retrieval-Augmented Generation) to search relevant memories and stream LLM responses with tool calling support.
  559. - **Toggle** via the floating chat icon at bottom-right
  560. - **Semantic search** finds the most relevant memories as context
  561. - **Streaming responses** with clickable `[Memory #ID]` references that focus the graph node
  562. - **Tool calling** — the LLM can create, update, and delete memories directly from chat (e.g., "save this as a memory", "delete memory #42", "update memory #10 with...")
  563. - Works on both the local server and Cloudflare Pages deployment
  564. **Configure the chat model:**
  565. | Backend | Variable | Default |
  566. |---------|----------|---------|
  567. | Local server | `CHAT_MODEL` env var | Falls back to `MEMORA_LLM_MODEL` |
  568. | Cloudflare Pages | `CHAT_MODEL` in `wrangler.toml` | `deepseek/deepseek-chat` |
  569. Requires an OpenAI-compatible API (`OPENAI_API_KEY` + `OPENAI_BASE_URL` for local, `OPENROUTER_API_KEY` secret for Cloudflare). The chat model must support tool use (function calling).
  570. </details>
  571. <details id="llm-deduplication">
  572. <summary><big><big><strong>LLM Deduplication</strong></big></big></summary>
  573. Find and merge duplicate memories using AI-powered semantic comparison:
  574. ```python
  575. # Find potential duplicates (uses cross-refs + optional LLM analysis)
  576. memory_find_duplicates(min_similarity=0.7, max_similarity=0.95, limit=10, use_llm=True)
  577. # Merge duplicates (append, prepend, or replace strategies)
  578. memory_merge(source_id=123, target_id=456, merge_strategy="append")
  579. ```
  580. **LLM Comparison** analyzes memory pairs and returns:
  581. - `verdict`: "duplicate", "similar", or "different"
  582. - `confidence`: 0.0-1.0 score
  583. - `reasoning`: Brief explanation
  584. - `suggested_action`: "merge", "keep_both", or "review"
  585. Works with any OpenAI-compatible **chat** API (OpenAI, OpenRouter, Azure, etc.) via `OPENAI_BASE_URL`. OpenRouter is fine for this LLM path; it does **not** provide embeddings — configure embeddings separately (see Semantic Search & Embeddings).
  586. </details>
  587. <details id="document-storage">
  588. <summary><big><big><strong>Document Storage</strong></big></big></summary>
  589. Store structured documents (research reports, architecture decisions, post-mortems) as searchable fragment trees:
  590. ```python
  591. # Store a markdown document — auto-parsed into typed fragments
  592. memory_store_document(
  593. content="# Research Report\n\n## Evidence Table\n| Claim | Confidence |\n...",
  594. document_key="research/memora-enhancements-2026-04-08",
  595. tags=["memora/research"]
  596. )
  597. # Returns: {root_id: 230, fragment_count: 100, node_map: {claim: [...], plan_item: [...], ...}}
  598. # Retrieve the full document or specific fragment types
  599. memory_get_document(document_key="research/memora-enhancements-2026-04-08")
  600. memory_get_document(document_key="...", node_kinds=["claim"], content_mode="full")
  601. # Delete a document and all its fragments
  602. memory_delete_document(document_key="research/memora-enhancements-2026-04-08")
  603. ```
  604. **How it works:** The parser splits markdown by structure — tables become individual claims, numbered lists become plan items, URL lists become references, and risk sections become risk fragments. Each fragment is independently searchable via `memory_semantic_search` while the full document is retrievable as a unit.
  605. **Fragment types:** `claim`, `plan_item`, `reference`, `section_chunk`, `risk`
  606. **Integrity guards:** Document fragments are protected from accidental modification:
  607. - `memory_delete` requires `force=True` for fragments
  608. - `memory_merge` refuses to merge fragments
  609. - `memory_absorb` excludes fragments from similarity matching
  610. - `memory_find_duplicates` and `memory_detect_supersessions` skip fragments
  611. - Graph UI hides fragments, shows only the document root node
  612. </details>
  613. <details id="memory-automation-tools">
  614. <summary><big><big><strong>Memory Automation Tools</strong></big></big></summary>
  615. Structured tools for common memory types:
  616. ```python
  617. # Create a TODO with status and priority
  618. memory_create_todo(content="Implement feature X", status="open", priority="high", category="backend")
  619. # Create an issue with severity
  620. memory_create_issue(content="Bug in login flow", status="open", severity="major", component="auth")
  621. # Create a section placeholder (hidden from graph)
  622. memory_create_section(content="Architecture", section="docs", subsection="api")
  623. ```
  624. </details>
  625. <details id="memory-insights">
  626. <summary><big><big><strong>Memory Insights</strong></big></big></summary>
  627. Analyze stored memories and surface actionable insights:
  628. ```python
  629. # Full analysis with LLM-powered pattern detection
  630. memory_insights(period="7d", include_llm_analysis=True)
  631. # Quick summary without LLM (faster, no API key needed)
  632. memory_insights(period="1m", include_llm_analysis=False)
  633. ```
  634. Returns:
  635. - **Activity summary** — memories created in the period, grouped by type and tag
  636. - **Open items** — open TODOs and issues with stale detection (configurable via `MEMORA_STALE_DAYS`; `memory_insights` default 14, graph UI default 30 — same variable, two consumers)
  637. - **Consolidation candidates** — similar memory pairs that could be merged
  638. - **LLM analysis** — themes, focus areas, knowledge gaps, and a summary (requires `OPENAI_API_KEY`)
  639. </details>
  640. <details id="memory-linking">
  641. <summary><big><big><strong>Memory Linking</strong></big></big></summary>
  642. Manage relationships between memories:
  643. ```python
  644. # Create typed edges between memories
  645. memory_link(from_id=1, to_id=2, edge_type="implements", bidirectional=True)
  646. # Edge types: references, implements, supersedes, extends, contradicts, related_to
  647. # Remove links
  648. memory_unlink(from_id=1, to_id=2)
  649. # Boost memory importance for ranking
  650. memory_boost(memory_id=42, boost_amount=0.5)
  651. # Detect clusters of related memories
  652. memory_clusters(min_cluster_size=2, min_score=0.3)
  653. ```
  654. </details>
  655. <details id="knowledge-graph-export">
  656. <summary><big><big><strong>Knowledge Graph Export (Optional)</strong></big></big></summary>
  657. For offline viewing, export memories as a static HTML file:
  658. ```python
  659. memory_export_graph(output_path="~/memories_graph.html", min_score=0.25)
  660. ```
  661. This is optional - the Live Graph Server provides the same visualization with real-time updates.
  662. </details>
  663. <details id="neovim-integration">
  664. <summary><big><big><strong>Neovim Integration</strong></big></big></summary>
  665. Browse memories directly in Neovim with Telescope. Copy the plugin to your config:
  666. ```bash
  667. # For kickstart.nvim / lazy.nvim
  668. cp nvim/memora.lua ~/.config/nvim/lua/kickstart/plugins/
  669. ```
  670. **Usage:** Press `<leader>sm` to open the memory browser with fuzzy search and preview.
  671. Requires: `telescope.nvim`, `plenary.nvim`, and `memora` installed in your Python environment.
  672. </details>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.