ctx-memory
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ctx-memorywhere did we leave off on the auth project?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
local-shared-memory-mcp
๐ง In progress. Early development: tools, CLI commands and the storage format may change.
One local memory that every AI tool shares. Start in Claude, continue in Cursor, Codex, Gemini CLI or opencode, and nothing has to be re-explained. Everything lives in one SQLite file (~/.memory/ctx-memory.db) behind an MCP server. No cloud, no account, no native build (Node >= 22.13, built-in node:sqlite + FTS5).
Claude Desktop โโ
Cursor โโผโโโบ ctx-memory MCP server โโโบ ~/.memory/ctx-memory.db
Codex / any MCP โQuick start
npm install
node src/cli.js init # Claude Desktop, Cursor, Windsurf (backs up configs as .bak)
claude mcp add ctx-memory -- node /path/to/local-shared-memory-mcp/src/cli.js serve # Claude CodeRestart the apps. Set MEMORY_DB_PATH to move the database.
Related MCP server: identity-storage-mcp
Switching models
In the tool you are leaving: "Save a handoff for project
myapp: goal, decisions, state, next steps."In the next tool: "Call get_context for project
myappand continue."
Use the same project name everywhere, ask for get_context yourself (most tools don't call it automatically; Claude Code with the hooks installed does, see Auto-save), and remember small facts as you go. For tools without MCP (e.g. ChatGPT web): node src/cli.js export myapp and paste the output.
Tools
Tool | Purpose |
| Latest handoff + top memories, capped by |
| Save a fact, preference, decision, task or note (tags, project, importance 1-5, dedupes) |
| Keyword search, ranked by relevance and importance (5 results by default) |
| Delete a memory by id |
| Store a "where we left off" summary |
| Projects with memory counts |
| Full memory as text, no cap |
Fast and small: FTS5 search (AND first, prefix and stemming, filler words ignored); context is ranked by importance and recency, near-duplicates collapsed, and replies are compact text cut at the token cap:
Handoff (2d ago, claude): Goal: ship auth. Next: login route.
#2 API runs on port 9090
#1 pref: I prefer tabs over spaces #style #code
(+12 more; use recall)Auto-save
All tools: the server tells models to
rememberproactively, andget_contextreminds them tosave_handoffbefore the chat ends. Models can still ignore this.Claude Code (hooks): loads memory automatically at session start and saves a handoff at session end, with no model involved. Hooks work only in Claude Code; other tools get the nudges above.
node src/cli.js hooks install # prints the settings.json block
node src/cli.js hooks install --write # merges it into ~/.claude/settings.json (backs up first)
node src/cli.js hooks install --summarize # at session end, also ask `claude -p` for a real handoff + candidate memories (uses some of your Claude usage)The project name is the folder Claude Code runs in (override with MEMORY_PROJECT). Without --summarize the end-of-session handoff is a free, crude extract of your last requests and the last reply.
Safeguards: likely secrets (API keys, tokens, password=) are redacted before anything auto-saved is stored. Memories captured by --summarize start pending and stay out of get_context and recall until you run node src/cli.js approve <id|all> (see them with pending, drop one with reject <id>). MEMORY_AUTOSAVE=off disables saving.
Other AI tools
Configs below follow each tool's documented format and are not all tested. Replace /path/to/local-shared-memory-mcp with your clone. Restart the tool afterwards.
Gemini CLI, ~/.gemini/settings.json:
{ "mcpServers": { "ctx-memory": { "command": "node", "args": ["/path/to/local-shared-memory-mcp/src/cli.js", "serve"] } } }Codex CLI, ~/.codex/config.toml:
[mcp_servers.ctx-memory]
command = "node"
args = ["/path/to/local-shared-memory-mcp/src/cli.js", "serve"]opencode, ~/.config/opencode/opencode.json:
{ "mcp": { "ctx-memory": { "type": "local", "command": ["node", "/path/to/local-shared-memory-mcp/src/cli.js", "serve"], "enabled": true } } }CLI and web viewer
node src/cli.js add "I prefer tabs" -k preference -t style -p myapp # also: list, search, edit, forget, projects
node src/cli.js handoff save "Goal: ship auth." -p myapp --from claude # or: handoff show; stdin works too
node src/cli.js export myapp # Markdown to paste anywhere
node src/cli.js import notes.md -p myapp # each "- line" becomes a memory
node src/cli.js ui # read-only viewer at http://127.0.0.1:4777
node src/cli.js usage --days 30 # tokens this server sent to your AIs
node src/cli.js pending # auto-saved memories awaiting review; then: approve <id|all> | reject <id>The viewer shows memories (search, project/kind/tag filters; auto-saved ones show a "pending review" badge until approved), handoffs, a get_context preview with token size, and a Usage tab. It binds to 127.0.0.1, answers GET only and refuses non-local Host headers.
Usage tracking stores one row per tool call (time, tool, AI app, project, estimated tokens = chars รท 4), never memory text, and prunes after 90 days. Turn it off with MEMORY_USAGE=off.
Limits and roadmap
Search matches words, not meaning, and a model saves memory only if it chooses to call the tools.
Planned: editing and deleting in the viewer, approve/reject buttons for pending memories in the viewer (the command line already has them), merge duplicates, pinning, expiry and cleanup, semantic search, and an HTTP/SSE mode for ChatGPT and other remote clients.
Run tests with npm test.
License
Available Tools
7 toolsexport_markdownC
Full memory as text, to paste into an AI without MCP.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and largely fails. It doesn't state that this is a read-only/export operation, how 'full memory' is scoped, whether project filtering applies, or anything about the return format beyond 'as text'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. It is efficiently sized, though arguably too terse for the missing behavioral and parameter context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an undocumented project parameter, no annotations, and no output schema, the description leaves key questions unanswered: what scope is exported, whether project filters, and what the output looks like. It is not complete enough for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description never mentions the 'project' parameter. An agent cannot tell whether this exports all projects or a single one, so the description does not compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and output form: it exports the full memory as text/markdown. The verb 'export' comes from the name rather than the description, and it doesn't explicitly distinguish itself from siblings like recall or get_context, but the format-based purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'To paste into an AI without MCP' implies a usage context, but it never states when to choose this over recall or get_context. There is no exclusion or alternative guidance beyond the implied 'no-MCP' scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
forgetC
Delete a memory by id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Delete' implies irreversible destruction, but it does not state whether the removal is permanent or soft, what happens if the id does not exist, or whether any permission is required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the verb and resource first and the scoping parameter last. Efficient, though its brevity contributes to the missing behavioral detail rather than being purely economical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema the description is minimal but not unusable. However, with no annotations and no schema descriptions, the destructive semantics and error behavior remain undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. 'By id' conveys only that the id selects the memory to remove; it adds no format, type, or validity details beyond the bare parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (delete) and resource (a memory), scoped by id. This is clearly distinguishable from siblings like remember (create) and recall (read), though the description does not explicitly name those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as recall or remember. The intent is inferable from the verb, but there are no stated conditions, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_contextA
Latest handoff + top memories. Call first in every chat.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | ||
| max_tokens | No | size cap for the reply |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose what content comes back (handoff + memories) and the ordering expectation. However it says nothing about scope/empty state (what if no project or no handoff exists), whether the call is read-only, or rate/cost characteristics of an aggregate fetch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with what it returns and immediately followed by the usage directive. Nothing extraneous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param read tool with no output schema, the description covers intent and timing but omits scoping behavior (project default), return shape/size implications, and failure modes. Adequate to call, incomplete to call well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%; max_tokens is documented in the schema but 'project' is undocumented there. The description mentions neither parameter, so it fails to compensate for the gap โ an agent cannot tell from the description whether omitting project yields a global or default-scoped context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the two things it returns (latest handoff + top memories), which is a specific resource pair rather than a tautology of 'get_context'. It implicitly contrasts with save_handoff/recall by being the read-and-prime entry point, but it never explicitly names a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call first in every chat' gives an explicit, actionable trigger for when to use it. It stops short of naming alternatives (e.g., why not recall or list_projects first) or stating exclusions, so it is clear context without full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_projectsC
Projects with memory counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden and delivers almost none of it: no statement that the operation is read-only, no pagination or scope behavior, no auth requirements, no hint of what a 'memory count' represents. Only the word 'Projects' plus a count vaguely implies a non-mutating enumeration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five words with zero filler โ nothing redundant and the resource is front-loaded. It is terse almost to the point of being a label rather than a description, which keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is genuinely simple (no params, no nested schema), but there is no output schema, so the description is the only place the return value could be explained โ and 'memory counts' is left undefined. With the safety profile also absent from annotations, the definition is only marginally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema declares zero parameters, so there is nothing for the description to disambiguate; baseline for a no-param tool is 4. Nothing in the description contradicts or duplicates a parameter it does not have.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The fragment 'Projects with memory counts' does identify the resource (projects) and the payload (memory counts), but it lacks a verb and never states that it lists or enumerates anything. It is also not distinguishable from the other read-oriented siblings (recall, get_context) beyond the resource noun, so purpose is only implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of alternatives among recall/get_context/export_markdown, and no exclusions. An agent must infer from the name alone that this is the discovery step before recalling memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
recallC
Search memory by keywords.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| limit | No | ||
| query | Yes | ||
| project | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden, and it discloses almost nothing. 'Search' implies a non-destructive read, but there is no statement about whether results are scoped to a project, how results are ranked or paginated, whether an empty result is a failure, or what the limit applies to.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single short sentence with no filler and the core concept is front-loaded, which is structurally good. However, the brevity is the result of under-specification rather than disciplined editing, so it does not earn a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with zero schema description coverage, no annotations, and no output schema, the description is materially incomplete. An agent cannot tell how to scope the search by kind or project, nor what the limit does, from anything provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 4 parameters, and the description only gestures at the query concept via 'keywords'. The kind enum (fact/preference/decision/task/note), the project scope filter, and the limit default/max of 5/30 are never explained, leaving three of four parameters undocumented in both schema and prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and resource ('memory') plus the matching mechanism ('by keywords'), so the agent knows this is a retrieval tool rather than a write. It does not differentiate itself from the sibling get_context, which is presumably also a memory-read tool, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use recall versus get_context, list_projects, or other siblings, and no mention of prerequisites or exclusions. The agent must infer usage entirely from the name and one-line description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rememberC
Save a durable fact, preference, decision or task.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | fact | |
| tags | No | ||
| text | Yes | one self-contained statement | |
| source | No | which AI/app is saving | |
| project | No | global | |
| importance | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond 'durable'. It does not say whether writes are deduplicated, append-only, scoped to a project, or how conflicts are resolved โ all material for a persistence tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no filler; the verb leads and the accepted content types follow. It is efficient, though arguably too terse to be informative given the parameter surface.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter persistence tool with no annotations and no output schema, the definition leaves too much unspecified: retention, project scoping, importance scale meaning, and duplicate handling are all absent. Nothing an agent needs to call it correctly is covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% across 6 parameters, so the description would need to compensate. It enumerates four of the five kind enum values (omitting 'note', which is slightly misleading) but says nothing about importance, tags, project, or source semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Save) and the resource types it accepts (durable fact, preference, decision, task), which reads as a write-side memory tool. It does not name or contrast with siblings like recall or save_handoff, but an agent can still tell it apart by the persist-a-statement action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this over save_handoff, export_markdown, or recall, and no mention of prerequisites or when-not-to-use. The only implied usage is that the content must be a durable statement, which the agent must infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
save_handoffB
Save a where-we-left-off summary for the next AI.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | global | |
| summary | Yes | goal, decisions, current state, next steps | |
| from_model | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden of behavioral disclosure, and it says nothing about whether saving overwrites a prior handoff for the same project, whether writes are persistent, or what permissions are needed. For a mutation tool with zero annotation coverage this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the action front-loaded and no filler; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter write tool with no annotations and no output schema, the description is too thin: it omits the project scoping behavior, the meaning of the optional parameters, and any indication of what happens on repeat saves.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'summary' is documented), and the description mentions no parameters at all. It does not explain the 'project' grouping key or what 'from_model' is for, so it fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource: 'Save a where-we-left-off summary'. The phrase 'for the next AI' makes the intent concrete and separates it from the storage/retrieval siblings (remember, recall). It does not explicitly contrast with the closest sibling, remember, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'for the next AI' implies the trigger is an end-of-session handoff, giving implied usage context. However, it never says when to prefer this over remember, nor when not to use it, leaving the agent to infer the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v0.1.0- First observed
export_markdown - First observed
forget - First observed
get_context - First observed
list_projects - First observed
recall - First observed
remember - First observed
save_handoff
TDQS
Scored across 7 tools
Most tools have distinct purposes: remember (write), recall (keyword search), forget (delete), save_handoff (session summary), list_projects, export_markdown. The main overlap is get_context vs recall (both retrieve memories) and remember vs save_handoff (both persist), but descriptions make the boundaries clear enough to avoid most misselection.
All names are verb-first and lowercase, with verb_noun forms (get_context, save_handoff, list_projects, export_markdown) alongside single-verb forms (remember, recall, forget). The mix is minor and still highly readable and predictable.
Seven tools is well-scoped for a memory server, covering the core write/read/delete/list/export surface without redundancy. Each tool earns its place.
Covers the full lifecycle: write (remember, save_handoff), read (get_context, recall), delete (forget), plus list_projects and export_markdown. Minor gaps exist (no update/edit of an existing memory, no get-by-id), but these are workable via forget+remember.
Maintenance
Related MCP Connectors
Cross-tool persistent memory and context for AI assistants over MCP.
- LogRackOAuthai.lograck
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
1 Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
- mcpOAuthai.butlerbrain
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
- AlicenseCqualityAmaintenanceProvides persistent, local-first AI memory across sessions via MCP tools for storing, searching, and retrieving context from past interactions.31962 PyPI1MIT
- AlicenseAqualityDmaintenanceProvides persistent, inspectable memory storage for AI agents using SQLite. Agents can store, recall, and search memories across sessions via three MCP tools.3MIT
- AlicenseAqualityBmaintenanceProvides persistent, searchable memory for AI agents across any MCP-compatible client, storing project context, user preferences, and session learnings locally in SQLite with tools to save, retrieve, search, and manage them.125 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables agents to store conversational turns in a single SQLite store and recall relevant context through lexical, entity, dense, and recent views without an LLM in the recall loop. It exposes MCP tools for remembering, bulk ingest, recall, stats, and session deletion, with persistent indexes and zero-token maintenance.-