Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 15 additions & 14 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,17 @@
# place automatically. Run `npx -y @agentmemory/agentmemory@latest doctor`
# to verify that the daemon reads the env you expect.
#
# Defaults shown in comments. Listed in priority order — the first key
# present wins on the LLM detection path (see src/config.ts::detectProvider).
# Defaults shown in comments. No provider is ever picked from a key alone:
# agentmemory sends session content to an outside AI provider only after you
# name one with AGENTMEMORY_LLM_PROVIDER or EMBEDDING_PROVIDER.

# -----------------------------------------------------------------------------
# 1. LLM provider — pick ONE
# 1. LLM provider: off unless you choose one
# -----------------------------------------------------------------------------
#
# Without a provider key, agentmemory runs in noop mode: observations are
# Without AGENTMEMORY_LLM_PROVIDER, agentmemory runs in noop mode and sends no
# session content to an LLM, even when a provider key is in the environment.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
# In noop mode: observations are
# indexed via zero-LLM synthetic compression and BM25 recall still works,
# but LLM-backed summarisation / reflection / consolidation are disabled.
# A provider key alone does not enable LLM-written observation compression;
Expand All @@ -39,13 +42,12 @@
# AGENTMEMORY_CAPTURE_SPOOL_DIR= # Spool folder (default <data dir>/capture-spool)
# AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES=5242880 # Spool size limit
# AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS=168 # Spooled records older than this are dropped
# The detection order is OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY
# → GEMINI_API_KEY → OPENROUTER_API_KEY → noop.
# To turn on LLM summaries, set AGENTMEMORY_LLM_PROVIDER and that provider's key.
# AGENTMEMORY_LLM_PROVIDER=anthropic # anthropic | openai | gemini | openrouter | minimax

# OPENAI_API_KEY=sk-... # Activates both the OpenAI-compatible LLM provider (DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama via `/v1`) and OpenAI embeddings. Set OPENAI_API_KEY_FOR_LLM=false to scope it to embeddings only.
# OPENAI_API_KEY=sk-... # Used by AGENTMEMORY_LLM_PROVIDER=openai (OpenAI-compatible: DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama via `/v1`) and by EMBEDDING_PROVIDER=openai
# OPENAI_BASE_URL=https://api.openai.com # Override for OpenAI-compatible providers
# OPENAI_MODEL=gpt-5.6-luna # Default OpenAI-compatible chat model
# OPENAI_API_KEY_FOR_LLM=false # Skip OpenAI auto-detection for LLM; key stays active for embeddings

# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_MODEL=claude-sonnet-5 # Default Anthropic model
Expand Down Expand Up @@ -74,18 +76,17 @@
# Stop-hook recursion when invoked from inside Claude Code.
# AGENTMEMORY_ALLOW_AGENT_SDK=true

# FALLBACK_PROVIDERS=anthropic,gemini # Comma-separated chain tried after the primary provider returns an error (e.g. rate limit)
# FALLBACK_PROVIDERS=anthropic,gemini # Comma-separated chain tried after the chosen AGENTMEMORY_LLM_PROVIDER returns an error (e.g. rate limit); ignored when no provider is chosen
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

# -----------------------------------------------------------------------------
# 2. Embedding provider — auto-detected, override via EMBEDDING_PROVIDER
# 2. Embedding provider: off unless you set EMBEDDING_PROVIDER
# -----------------------------------------------------------------------------
#
# Without an embedding provider, vector embeddings are disabled. `mem::search`
# uses BM25; `mem::smart-search` can also fuse structural graph matches when
# graph data exists. Remote
# provider detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
# OPENAI_API_KEY → VOYAGE_API_KEY → COHERE_API_KEY → OPENROUTER_API_KEY →
# BM25-only. Local embeddings are an explicit opt-in, not the keyless default.
# graph data exists. Cloud embeddings send memory text to that provider and run
# only when EMBEDDING_PROVIDER names it; a key alone never turns them on.
# Local embeddings are an explicit opt-in too, not the keyless default.
# `EMBEDDING_PROVIDER=local` uses Xenova/all-MiniLM-L6-v2 (384-dim) on-device;
# the first embedding request downloads the model and needs network access.

Expand Down
28 changes: 17 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -878,7 +878,7 @@ Keyless installs disable vector embeddings: `mem::search` uses BM25, while `smar
EMBEDDING_PROVIDER=local
```

The normal npm install includes the optional `@huggingface/transformers` runtime. The first embedding request downloads `Xenova/all-MiniLM-L6-v2`, so it needs network access and can take longer; subsequent inference runs on-device. Remote providers are auto-detected from their keys unless `EMBEDDING_PROVIDER` overrides them.
The normal npm install includes the optional `@huggingface/transformers` runtime. The first embedding request downloads `Xenova/all-MiniLM-L6-v2`, so it needs network access and can take longer; subsequent inference runs on-device. Remote embedding providers run only when `EMBEDDING_PROVIDER` names one of them (`gemini`, `openai`, `voyage`, `cohere`, `openrouter`) and its key is set. A key on its own never turns on remote embeddings.

| Provider | Model | Cost | Notes |
|---|---|---|---|
Expand Down Expand Up @@ -1056,17 +1056,17 @@ The viewer server binds to `127.0.0.1` by default and attaches the server secret

### LLM Providers

agentmemory auto-detects providers from your environment. A provider makes LLM-backed operations available, but provider configuration alone does not enable LLM-written observation compression. That path requires both a provider and `AGENTMEMORY_AUTO_COMPRESS=true`.
agentmemory sends session content to an LLM only after you select a provider with `AGENTMEMORY_LLM_PROVIDER`, or turn on the Claude Agent SDK fallback with `AGENTMEMORY_ALLOW_AGENT_SDK=true`. A key that exists in your environment for another tool is never enough. A selected provider makes LLM-backed operations available (session summaries, consolidation, reflection), but it does not enable LLM-written observation compression on its own. That path also requires `AGENTMEMORY_AUTO_COMPRESS=true`.

| Provider | Config | Notes |
|----------|--------|-------|
| **No-op (default)** | No config needed | LLM-backed compress/summarize is disabled. Synthetic compression and BM25 recall still work. See `AGENTMEMORY_ALLOW_AGENT_SDK` below if you used to rely on the Claude-subscription fallback. |
| Anthropic API | `ANTHROPIC_API_KEY` | Per-token billing |
| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
| Gemini | `GEMINI_API_KEY` | Also enables embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | Any model |
| OpenAI API | `OPENAI_API_KEY` | Default `gpt-5.6-luna`, override with `OPENAI_MODEL` |
| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) or `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=<your model>` | Anything OpenAI-API-compatible. Zero cost, runs on your hardware. See [Local models](#local-models-ollama--lm-studio--vllm) below. |
| Anthropic API | `AGENTMEMORY_LLM_PROVIDER=anthropic` + `ANTHROPIC_API_KEY` | Per-token billing |
| MiniMax | `AGENTMEMORY_LLM_PROVIDER=minimax` + `MINIMAX_API_KEY` | Anthropic-compatible |
| Gemini | `AGENTMEMORY_LLM_PROVIDER=gemini` + `GEMINI_API_KEY` | Gemini embeddings need `EMBEDDING_PROVIDER=gemini` as well |
| OpenRouter | `AGENTMEMORY_LLM_PROVIDER=openrouter` + `OPENROUTER_API_KEY` | Any model |
| OpenAI API | `AGENTMEMORY_LLM_PROVIDER=openai` + `OPENAI_API_KEY` | Default `gpt-5.6-luna`, override with `OPENAI_MODEL` |
| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `AGENTMEMORY_LLM_PROVIDER=openai` + `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) or `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=<your model>` | Anything OpenAI-API-compatible. Zero cost, runs on your hardware. See [Local models](#local-models-ollama--lm-studio--vllm) below. |
| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in only. Spawns `@anthropic-ai/claude-agent-sdk` sessions; it used to cause unbounded Stop-hook recursion, so it is no longer the default. |

### Local models (Ollama / LM Studio / vLLM)
Expand All @@ -1082,6 +1082,7 @@ ollama serve

```env
# ~/.agentmemory/.env
AGENTMEMORY_LLM_PROVIDER=openai
OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:8b
Expand All @@ -1093,6 +1094,7 @@ Open LM Studio → Local Server tab → Start Server. Pick any chat model from t

```env
# ~/.agentmemory/.env
AGENTMEMORY_LLM_PROVIDER=openai
OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
Expand Down Expand Up @@ -1165,7 +1167,7 @@ The default file store needs no separate database service. Redis is optional wit

### Config File

Put agentmemory runtime configuration in `~/.agentmemory/.env` instead of exporting variables in every shell. If the viewer shows a setup hint like `export ANTHROPIC_API_KEY=...`, copy it into this file as `ANTHROPIC_API_KEY=...` without the `export` prefix, then restart agentmemory. Set `AGENTMEMORY_ENV_FILE` to use another env-file path.
Put agentmemory runtime configuration in `~/.agentmemory/.env` instead of exporting variables in every shell. If the viewer shows a setup hint like `export ANTHROPIC_API_KEY=...`, copy it into this file as `ANTHROPIC_API_KEY=...` without the `export` prefix, add `AGENTMEMORY_LLM_PROVIDER=anthropic` to select it, then restart agentmemory. Set `AGENTMEMORY_ENV_FILE` to use another env-file path.

Process environment variables take precedence over values in the file. Restart the server after changing its configuration.

Expand All @@ -1185,7 +1187,7 @@ AGENTMEMORY_AUTO_COMPRESS=true

LLM-written observation compression requires both lines: access to an LLM provider (including this explicit subscription fallback) and `AGENTMEMORY_AUTO_COMPRESS=true`. A provider by itself leaves the default synthetic compression path in place.

Consolidation (graph nodes, lessons, crystals) is on by default whenever an LLM provider is configured. Explicitly opt out with `CONSOLIDATION_ENABLED=false` if you want LLM-free operation. Graph extraction is a separate flag:
Consolidation (graph nodes, lessons, crystals) is on by default whenever an LLM provider is selected with `AGENTMEMORY_LLM_PROVIDER`, or the Agent SDK fallback is on with `AGENTMEMORY_ALLOW_AGENT_SDK=true`. Explicitly opt out with `CONSOLIDATION_ENABLED=false` if you want LLM-free operation. Graph extraction is a separate flag:

```env
GRAPH_EXTRACTION_ENABLED=true
Expand All @@ -1203,7 +1205,11 @@ EMBEDDING_PROVIDER=local
# Optional automatic context injection through the shared hooks
# AGENTMEMORY_INJECT_CONTEXT=true

# Optional LLM-written compression; also requires a configured provider
# Optional outside LLM for summaries and consolidation. A key alone does nothing;
# this line selects the provider whose key agentmemory may use.
# AGENTMEMORY_LLM_PROVIDER=anthropic

# Optional LLM-written compression; also requires AGENTMEMORY_LLM_PROVIDER
# AGENTMEMORY_AUTO_COMPRESS=true

# Show 8 essential MCP tools instead of the default 54
Expand Down
17 changes: 15 additions & 2 deletions plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,13 +1,26 @@
{
"name": "agentmemory",
"version": "0.9.31",
"description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 54 MCP tools, 17 skills, real-time viewer.",
"description": "Persistent local memory for Claude. Hooks record prompts, tool calls and replies to a separately installed agentmemory server on your machine; skills and 54 MCP tools search and manage that memory. No outside AI provider is used unless you enable one.",
"author": {
"name": "Rohit Ghumare",
"url": "https://github.com/rohitg00"
},
"license": "Apache-2.0",
"homepage": "https://github.com/rohitg00/agentmemory",
"repository": "https://github.com/rohitg00/agentmemory",
"skills": ["./skills/"]
"skills": ["./skills/"],
"userConfig": {
"agentmemory_url": {
"type": "string",
"title": "agentmemory server URL",
"description": "Where the hooks and MCP server reach your agentmemory server. Leave empty to use AGENTMEMORY_URL from your environment when it is set, otherwise http://localhost:3111. A remote server must use https."
},
"agentmemory_secret": {
"type": "string",
"title": "agentmemory server secret",
"description": "Only needed for a remote agentmemory server. Leave empty for a server on this machine; the plugin then reads the local server's own secret and never sends it off this machine.",
"sensitive": true
}
}
}
3 changes: 1 addition & 2 deletions plugin/.devin-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,7 @@
"@agentmemory/mcp@0.9.31"
],
"env": {
"AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}",
"AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET:-}"
"AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}"
}
}
}
Expand Down
6 changes: 5 additions & 1 deletion plugin/.mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@
"mcpServers": {
"agentmemory": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/scripts/plugin-bridge.mjs"]
"args": ["${CLAUDE_PLUGIN_ROOT}/scripts/plugin-bridge.mjs"],
"env": {
"AGENTMEMORY_URL": "${user_config.agentmemory_url}",
"AGENTMEMORY_SECRET": "${user_config.agentmemory_secret}"
}
}
}
}
71 changes: 71 additions & 0 deletions plugin/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# agentmemory

agentmemory gives Claude persistent memory across sessions. Its hooks record what happens in each session, and its skills and MCP tools let Claude search that history, save decisions and lessons, and pick up earlier work. Everything is stored on your own machine by default.

## Install

```
/plugin install agentmemory --marketplace rohitg00/agentmemory
```

## Requirements

This plugin is a client for the agentmemory server, a separate program that you install and run yourself. The 54 MCP tools, the search index and the viewer all come from that server. Without it the hooks have nowhere to send events and the tools return errors.

Start the server in its own terminal with Node.js 20 or newer:

```bash
npx -y @agentmemory/agentmemory@latest
```

Keep it running while you use the plugin. Check it with `npx -y @agentmemory/agentmemory@latest status`. The server listens on `http://localhost:3111` and the viewer on `http://localhost:3113`.

When you enable the plugin, Claude Code asks for two optional settings: the server URL and the server secret. Leave both empty for a local server. If the URL is empty, the plugin uses `AGENTMEMORY_URL` from your environment when it is set. Claude Code keeps the secret in your system keychain; on systems without a keychain it keeps it in `~/.claude/.credentials.json`, a file readable only by your user. The plugin sends events and the secret only to a loopback address or an `https://` URL; for a remote `http://` URL it sends nothing.

## What the hooks record

The plugin registers 12 Claude Code hooks. They record:

- every prompt you submit, including prompts recovered from the session transcript when the session ends
- the name, input and output of each tool call, and the error when a call fails. This includes results returned by other connectors and MCP servers
- the final reply of the assistant and of each subagent, up to 4,000 characters
- session start and end, subagent start, notifications and completed tasks, with the working directory

Before storage, `<private>...</private>` blocks and common secret formats such as API keys and private keys are replaced with redaction markers. Long tool output is truncated.

## Where it is kept and for how long

The server stores everything in a local data folder:

- macOS: `~/Library/Application Support/agentmemory`
- Linux: `~/.local/share/agentmemory`
- Windows: `%APPDATA%\agentmemory`

If the server is down, hook events wait in a `capture-spool` folder inside the same data folder. The spool holds at most 5 MiB and drops events older than 7 days.

Data is kept until you delete it. Each session keeps at most 500 observations by default. Memories that carry an expiry date are removed automatically after that date.

## What can leave your machine

By default, nothing. Search uses local keyword matching, and no LLM is called. Content leaves your machine only when you turn on one of these options on the server:

- `AGENTMEMORY_LLM_PROVIDER` selects an LLM provider (Anthropic, OpenAI, Gemini, OpenRouter or MiniMax). Session summaries, consolidation and reflection then send excerpts of recorded content to it. A provider key that is already in your environment does nothing until you set this option. LLM compression of each observation stays off unless you also set `AGENTMEMORY_AUTO_COMPRESS=true`.
- `AGENTMEMORY_ALLOW_AGENT_SDK=true`, with no provider selected, sends the same excerpts to Claude through the Claude Agent SDK.
- `EMBEDDING_PROVIDER` set to `gemini`, `openai`, `voyage`, `cohere` or `openrouter` sends text to that service to build search vectors. `EMBEDDING_PROVIDER=local` runs on your machine after a one-time model download.
- A Redis state backend stores records on the Redis server you configure.
- Mesh sync sends memories to peer agentmemory servers that you register.

Context injection is also off by default. The plugin prints stored memory into the conversation only when you set `AGENTMEMORY_INJECT_CONTEXT=true`.

## View and delete your data

- Open the viewer at `http://localhost:3113`, or run `npx -y @agentmemory/agentmemory@latest status`.
- Export everything with the `memory_export` tool.
- Delete single memories with the `forget` skill or the `memory_governance_delete` tool.
- Delete everything: stop the server with `npx -y @agentmemory/agentmemory@latest stop`, then delete the data folder listed above. With a Redis state backend, also delete agentmemory's records from that Redis server, for example by flushing the Redis database you gave agentmemory.

Recalled memories are evidence from past sessions, not instructions. Claude should check them before acting on them.

Privacy policy: https://agent-memory.dev/privacy

Source and issues: https://github.com/rohitg00/agentmemory
Loading
Loading