Skip to main content
Glama
deenesjakoruzh
GhadiSaab

ctx-memory

by GhadiSaab
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ctx-memory

Memoria persistente para agentes de codificación LLM: Claude Code, Codex, Gemini CLI, OpenCode.

Cuando inicias una nueva sesión, el agente ya sabe en qué trabajaste la última vez: decisiones tomadas, archivos modificados, errores encontrados, convenciones aprendidas. Sin nube. Sin telemetría. Todo reside en una base de datos SQLite local en ~/.ctx-memory/store.db.

Cómo funciona

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: remem

Instalación

npm install -g ctx-memory
ctx-memory setup

El asistente de configuración:

  1. Detecta qué herramientas están instaladas (claude, codex, gemini, opencode)

  2. Pregunta cuáles integrar

  3. Escribe configuraciones de hook para cada herramienta

  4. Crea enlaces simbólicos de envoltorio en ~/.ctx-memory/bin/

  5. Añade ~/.ctx-memory/bin a tu PATH a través de ~/.bashrc / ~/.zshrc

Reinicia tu shell (o ejecuta source ~/.bashrc), luego usa tus herramientas normalmente: la memoria es automática.

Comandos

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

Servidor MCP

El servidor MCP se ejecuta como un proceso secundario junto a cada sesión de herramienta y expone seis herramientas:

Herramienta

Descripción

store_message

Almacena un mensaje de conversación para procesarlo al finalizar la sesión

store_event

Registra un evento de llamada a herramienta (edición de archivo, comando bash, etc.)

search_context

Busca en sesiones pasadas por similitud semántica o palabras clave

get_project_memory

Devuelve el documento completo de memoria del proyecto

list_sessions

Lista las sesiones recientes con objetivos y resultados

end_session

Finaliza una sesión y ejecuta la tubería de Capa 1 → Capa 2 → Capa 3

Para usar el servidor MCP de forma independiente con Claude Code, añade a ~/.claude/settings.json:

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

Arquitectura

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

Restricciones clave:

  • Todas las funciones de Capa 1/2/3 son puras: sin E/S, nunca lanzan errores

  • Los resúmenes se mantienen por debajo de 500 tokens

  • La búsqueda vectorial utiliza embeddings all-MiniLM-L6-v2 a través de sqlite-vec (384 dimensiones)

  • Base de datos SQLite única, modo WAL, claves foráneas activadas

Desarrollo

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

La ruta de la base de datos es por defecto ~/.ctx-memory/store.db. Puedes sobrescribirla con CTX_MEMORY_DB_PATH.

Licencia

MIT

Available Tools

6 tools
end_sessionC

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

ParametersJSON Schema
NameRequiredDescriptionDefault
outcomeYes
exit_codeNo
project_idYes
session_idYes

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
NameRequiredDescriptionDefault
project_idNo

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
NameRequiredDescriptionDefault
limitNo
project_idNo

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
NameRequiredDescriptionDefault
limitNo
queryYes
project_idNo

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
NameRequiredDescriptionDefault
argsNo
toolYes
resultNo
successNo
session_idYes

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
NameRequiredDescriptionDefault
roleYes
indexYes
contentYes
session_idYes

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.

  1. 6 tool updatesv1.0.4
    • First observedend_session
    • First observedget_project_memory
    • First observedlist_sessions
    • First observedsearch_context
    • First observedstore_event
    • First observedstore_message
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored across 6 tools

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

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • remem

    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.
    15
    32
    MIT

  • KOPENG

    djy89
    F
    license
    Not graded
    quality
    B
    maintenance
    Persistent, self-curating memory for coding agents. It enables local, zero-cost context recall through MCP tools with hybrid retrieval and autonomous consolidation.
    -

  • Leteo

    asanabrial
    A
    license
    A
    quality
    A
    maintenance
    Persistent memory for AI coding agents, storing decisions, bug fixes, conventions, and discoveries in a local SQLite database and automatically recalling them when relevant. Works with Claude Code, Codex, Cursor, Gemini CLI, and other MCP-compatible agents.
    22
    2
    MIT