de en es ja ko ru zh

ctx-memory

Name: ctx-memory
Author: GhadiSaab

by GhadiSaab

Overview Schema Related Servers Score Discussions

TypeScript

Local

ctx-memory

Persistent memory for LLM coding agents — Claude Code, Codex, Gemini CLI, OpenCode.

When you start a new session, the agent already knows what you worked on last time: decisions made, files touched, errors hit, conventions learned. No cloud. No telemetry. Everything lives in a local SQLite database at ~/.ctx-memory/store.db.

How it works

Session starts
      │
 Shell wrapper intercepts 'claude' (or codex/gemini/opencode)
      │
 MCP server starts alongside — injects prior context, exposes memory tools
      │
 During session: hooks fire on every tool call, messages buffered
      │
 Session ends (clean exit / Ctrl-C / crash)
      │
 Layer 1 → Layer 2 → Layer 3 pipeline runs
      │
      ├── Layer 1: extract weighted messages, events, decisions, errors, keywords
      ├── Layer 2: compress to ≤500-token digest, store in DB
      └── Layer 3: merge digest into project memory doc (markdown)

Next session: agent reads prior context automatically

Related MCP server: total-agent-memory

Install

npm install -g ctx-memory
ctx-memory setup

The setup wizard:

Detects which tools are installed (claude, codex, gemini, opencode)
Asks which ones to integrate
Writes hook configs for each tool
Creates wrapper symlinks in ~/.ctx-memory/bin/
Adds ~/.ctx-memory/bin to your PATH via ~/.bashrc / ~/.zshrc

Restart your shell (or source ~/.bashrc), then use your tools as normal — memory is automatic.

Commands

ctx-memory setup                        # interactive setup wizard
ctx-memory status                       # show configuration and stats
ctx-memory projects list                # list all projects
ctx-memory projects show <name>         # print full memory doc for a project
ctx-memory projects forget <name>       # reset memory (keeps sessions)
ctx-memory projects forget <name> --hard  # delete all sessions + data

MCP server

The MCP server runs as a sidecar alongside each tool session and exposes six tools:

Tool	Description
`store_message`	Buffer a conversation message for processing at session end
`store_event`	Record a tool call event (file edit, bash command, etc.)
`search_context`	Search past sessions by semantic similarity or keywords
`get_project_memory`	Return the full project memory doc
`list_sessions`	List recent sessions with goals and outcomes
`end_session`	Finalize a session and run the Layer 1 → Layer 2 → Layer 3 pipeline

To use the MCP server standalone with Claude Code, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "ctx-memory": {
      "command": "node",
      "args": ["/path/to/ctx-memory/dist/src/mcp/index.js"]
    }
  }
}

Architecture

src/
  cli/        — setup wizard, status, projects commands
  db/         — SQLite schema + CRUD (projects, sessions, events, digests, memory)
  layer1/     — pure message/event processing → weighted Layer1Output
  layer2/     — digest compression to ≤500 tokens → Layer2Digest
  layer3/     — merge digest into ProjectMemory markdown
  mcp/        — MCP server (handlers + stdio entry point)
  wrapper/    — shell wrapper (intercepts tool invocation, manages session lifecycle)
  hooks/      — hook config writers for Claude / Gemini / OpenCode

Key constraints:

All Layer 1/2/3 functions are pure — no I/O, never throw
Digests stay under 500 tokens
Vector search uses all-MiniLM-L6-v2 embeddings via sqlite-vec (384-dim)
Single SQLite DB, WAL mode, foreign keys on

Development

npm run build       # tsc → dist/
npm run dev         # tsc --watch
npm run test:run    # vitest (single-shot, 476+ tests)
npm test            # vitest (watch mode)

DB path defaults to ~/.ctx-memory/store.db. Override with CTX_MEMORY_DB_PATH.

License

MIT

Available Tools

6 tools

end_sessionC

Signal session end — runs Layer 1→2→3 pipeline, stores digest, updates project memory.

ParametersJSON Schema

Name	Required	Description	Default
`outcome`	Yes
`exit_code`	No
`project_id`	Yes
`session_id`	Yes

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It mentions mutation (updates memory, stores digest) but does not disclose side effects, authorization needs, or what happens to the session. The pipeline reference is not explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, front-loading the main action. However, it lacks structure such as bullet points or separate sections that could aid readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters, no output schema, and no annotations, the description is insufficient. It omits details about the pipeline, digest format, memory updates, and behavior for different outcomes and exit_code. The tool's effects are not fully contextualized.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no meaning to the parameters. It does not explain what 'outcome' values entail, what 'exit_code' represents, or how 'session_id' and 'project_id' are used beyond schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool signals session end and runs a pipeline, stores digest, and updates memory. It distinguishes from siblings like get_project_memory (read) or list_sessions (list), but the 'Layer 1→2→3 pipeline' is somewhat vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidance or alternatives are given. It is implied that this tool is used when ending a session, but there is no explicit when-to-use or when-not-to-use, nor any mention of prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_project_memoryC

Return the full project memory document (architecture, conventions, recent work, known issues).

ParametersJSON Schema

Name	Required	Description	Default
`project_id`	No

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description implies a read operation but does not disclose side effects, authentication needs, rate limits, or handling of missing parameters. With no annotations, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with verb and resource. Efficient but could be more structured by including parameter info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite low complexity, the description omits parameter explanation and output details. Not complete enough for reliable tool use, especially with an optional schema parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description does not mention the 'project_id' parameter or its role. The description adds no value beyond the schema for parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly identifies the tool's purpose with a specific verb ('Return') and resource ('full project memory document') and enumerates contents (architecture, conventions, recent work, known issues). This distinguishes it from siblings like search_context or list_sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance provided on when to use this tool versus alternatives (e.g., search_context for queries). The description is purely functional, offering no context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_sessionsC

List recent sessions for a project with their goals and outcomes.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`project_id`	No

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It mentions 'recent' implying ordering, but lacks details on pagination, side effects, authentication needs, or output format. Behavioral transparency is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is too brief to be useful. It omits critical information about parameters and usage, making it under-specified rather than concisely complete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given two parameters and no output schema or annotations, the description should provide more context about what 'recent' means, how to use the limit parameter, and what the output looks like. It fails to do so, leaving the agent with incomplete guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain any parameters. It hints at project_id via 'for a project' but does not clarify limit or the required nature of project_id. The description adds no value over the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists recent sessions for a project, including goals and outcomes. It distinguishes itself from siblings like end_session and get_project_memory by focusing on listing rather than ending or retrieving memory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool over alternatives or any prerequisites. The description only states what the tool does, without context for the agent to decide between list_sessions and search_context or get_project_memory.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_contextB

Search past sessions for context relevant to a query. Uses embedding similarity, falls back to keyword search.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes
`project_id`	No

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes algorithmic behavior (embedding similarity with keyword fallback) but is missing other behavioral traits like read-only nature, scope (e.g., all sessions vs. user-specific), or return characteristics. No annotations provided, so burden is on description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each adding value. First sentence states purpose, second adds method detail. No redundancy or wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks explanation of output format, pagination, or scope of search. For a read tool with 3 parameters and no output schema, more context is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description does not explain any of the three parameters (query, limit, project_id). The word 'query' is used generically but not linked to the schema property.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description explicitly states 'Search past sessions for context relevant to a query,' clearly identifying the verb and resource. It is distinct from sibling tools like get_project_memory (project-level) and list_sessions (list-only).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 (e.g., get_project_memory). No when-not-to-use or prerequisite information provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

store_eventC

Record a tool call event (file edit, bash command, etc.) for the current session.

ParametersJSON Schema

Name	Required	Description	Default
`args`	No
`tool`	Yes
`result`	No
`success`	No
`session_id`	Yes

TDQS

C2.2/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose any behavioral traits such as side effects, idempotency, or authentication requirements. The description only states what the tool does, not how it behaves, which is insufficient for an agent to understand implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is efficiently worded and front-loaded. However, it is too terse given the tool's complexity, sacrificing necessary detail for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 5 parameters, nested objects, no output schema, and no annotations. The description fails to explain the role of each parameter, return value, or success conditions. It leaves significant gaps for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not add any meaning to the parameters (e.g., args, result, success, session_id). With 5 parameters including nested objects, the agent has no guidance on how to fill them correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Record a tool call event' and provides examples like 'file edit, bash command'. It specifies scope 'for the current session', which helps distinguish from sibling tools like store_message that store user messages. However, it could be more explicit about what constitutes a 'tool call event'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus its siblings (e.g., store_message, end_session). It lacks context for when an agent should choose store_event over others, leaving the agent to rely on tool names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

store_messageC

Buffer a conversation message for session-end processing.

ParametersJSON Schema

Name	Required	Description	Default
`role`	Yes
`index`	Yes
`content`	Yes
`session_id`	Yes

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It only states 'buffer' and 'session-end processing' but does not explain if messages are persisted, if there are limits, what happens on session end, or any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise and front-loads the core purpose. However, it sacrifices some useful detail that could be added without excessive length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 4 required parameters, no annotations, and no output schema, the description is too thin. It does not explain how messages are buffered, ordering, batching, or any constraints, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no parameter-level explanations. For example, 'role' and 'index' are not described, leaving their meaning ambiguous despite having enums or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'buffer' and resource 'conversation message', and specifies the purpose 'for session-end processing'. It effectively distinguishes itself from sibling tools like store_event or end_session.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description provides no explicit guidance on when to use this tool versus alternatives. No mention of when not to use it or any prerequisites, leaving the agent without decision support.

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. Dates show when Glama detected each change.

6 tool updatesv1.0.4Apr 27, 2026
- First observedend_session
- First observedget_project_memory
- First observedlist_sessions
- First observedsearch_context
- First observedstore_event
- First observedstore_message

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: session lifecycle (end_session), memory retrieval (get_project_memory, list_sessions, search_context), and data recording (store_event, store_message). No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case, e.g., end_session, get_project_memory, store_event. The naming is predictable and uniform.

Tool Count5/5

With 6 tools, the server covers core memory management operations without bloat. The count is well-scoped for the domain of session context and project memory.

Completeness5/5

The tool surface covers the full typical lifecycle: recording events/messages, searching and retrieving context, listing sessions, and finalizing sessions with memory updates. No obvious gaps.

Maintenance

ActivityStale

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Memoize — persistent agent memoryOAuth
io.github.harrisonford
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Knowledge & Memory Autonomous Agents
1
TeamShared B
io.github.xhad
Shared memory for coding agents. Stop re-explaining your codebase every session.
Knowledge & Memory Developer Tools
1221
ContextStream MCP ServerOAuth
io.github.contextstream
Project memory, semantic code search, and grounded agent context.
Knowledge & Memory Code Analysis RAG Systems
141
memory
com.lodekeep
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
Knowledge & Memory File Systems
1

Related MCP Servers

mnemo
Knowledge & Memory Developer Tools
arttttt
A
license
Not graded
quality
A
maintenance
A persistent, local memory layer for AI coding agents that remembers decisions, bugs, and rules across sessions with three core MCP verbs (recall, remember, search).
Updated 2 months ago (2026-06-30 20:59 UTC)
Apache 2.0
total-agent-memory
Knowledge & Memory Coding Agents
vbcherepanov
A
license
Not graded
quality
A
maintenance
Persistent, local memory for AI coding agents that learns how you work, not just what you said. Supports Claude Code, Codex CLI, Cursor, and any MCP client.
Updated 10 days ago (2026-08-27 16:44 UTC)
67
MIT
remem
Knowledge & Memory Developer Tools Autonomous Agents
majiayu000
A
license
A
quality
A
maintenance
Local-first persistent memory for Claude Code and OpenAI Codex CLI. A single Rust binary captures, distills, searches, and injects project memory across sessions via hooks, MCP, CLI, and localhost REST.
Updated a day ago (2026-09-05 15:42 UTC)
3
15
30
MIT
memini
Knowledge & Memory Developer Tools
lumayapartners
A
license
A
quality
B
maintenance
Local-first project memory for AI coding agents. Records failed attempts, fragile files, and decisions per repo, and warns the agent via hooks before it repeats a recorded mistake.
Updated a month ago (2026-07-22 13:48 UTC)
6
79
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/GhadiSaab/ctx-memory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server