How do I use agent-context?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-context record a note about the build gotcha we just hit" 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.

de en es ja ko ru zh

agent-context

by gkrisz22

Overview Schema Related Servers Score Discussions

TypeScript

Local

agent-context-mcp

Persistent, harness-agnostic project memory for AI coding agents.

A stateless MCP server that gives any agent — Claude Code, Codex, Kilo Code, OpenCode, Cursor — structured read/write access to a per-project ai_context/ folder of plain markdown. Decisions, plans, constraints and notes live in the repo, sync via git, and stay readable by agents that do not have the server installed.

The agent decides when and what to record. The server decides format and location. That opinionation is the point: give an agent free-form writes and the folder degrades into sludge.

What it is not

No code retrieval, no semantic search, no embeddings, no database, no daemon state. Pure file I/O. It composes with a code-search tool rather than competing with one.

Related MCP server: Jarvis Markdown MCP

Install

Needs Node ≥ 18. Nothing to install globally — every harness below runs it through npx.

npx agent-context-mcp init

init creates the ai_context/ skeleton, stubs project.md and constraints.md, appends the activation snippet to AGENTS.md, and prints the registration block for your harness. It never overwrites an existing file.

Register with your harness

Claude Code, from the project root:

claude mcp add agent-context -- npx -y agent-context-mcp .

Or commit a .mcp.json so the whole team gets it:

{
  "mcpServers": {
    "agent-context": {
      "command": "npx",
      "args": ["-y", "agent-context-mcp", "."]
    }
  }
}

Codex, in ~/.codex/config.toml:

[mcp_servers.agent-context]
command = "npx"
args = ["-y", "agent-context-mcp", "."]

Kilo Code, OpenCode, Cursor, Windsurf and other MCP clients take the same mcpServers JSON block in their own settings file.

The trailing . makes the server treat the harness's working directory as the project root. Pass an absolute path instead if your harness starts elsewhere. Transport is stdio only.

AGENTS.md snippet

init appends this; add it by hand if you would rather not run init. It is what actually makes agents use the tools:

## Persistent project context

This project uses the agent-context MCP server. At session start, call
`get_context` (no arguments) to orient yourself. When you make or the user
confirms a significant architectural/technical decision, call
`record_decision`. Persist gotchas and conventions with `record_note`.
Human-curated ground truth lives in ai_context/project.md and
ai_context/constraints.md — read them, never contradict them.

The folder

<project-root>/
  AGENTS.md                 entry point — yours, never written except by `init`
  ai_context/
    INDEX.md                auto-maintained table of contents (server-owned)
    project.md              what this project is (yours; server reads, never writes)
    constraints.md          hard rules and good practices (yours; read-only to the server)
    memory.md               notes, written via record_note
    decisions/
      0001-use-postgres.md  ADRs, written via record_decision
    plans/
      auth-refactor.md      mutable plans, written via update_plan

ai_context/ is created lazily on the first write, or up front by init.
INDEX.md is regenerated after every write and re-scanned from disk each time. Never hand-edit it.
Decisions are append-only. Superseding one means recording a new one that references it; the only edit ever made to an existing ADR is a - Superseded-by: NNNN metadata line.
Plans are mutable — update_plan overwrites.
project.md and constraints.md are human ground truth. The server reads them and never writes them.

Tools

Tool	Input	What it does
`get_context`	`topic?`	Reads the index (default), `project`, `constraints`, `memory`, `decisions` or `plans` lists, a decision ID like `0003`, or a plan slug.
`record_decision`	`title`, `context`, `decision`, `consequences`, `supersedes?`	Writes `decisions/NNNN-<slug>.md` as an ADR and links the superseded one both ways.
`record_note`	`category`, `content`	Appends a dated bullet to `memory.md` under Gotchas / Conventions / Learnings / Todos. Identical notes are deduplicated.
`update_plan`	`name`, `content`	Creates or fully overwrites `plans/<slug>.md`.
`list_context`	—	Lists every file under `ai_context/` with size and last-modified date.

Length caps are deliberate anti-sludge discipline, not storage limits: title 80 chars, ADR sections 1200 each, notes 500, plans 8000. Exceeding one returns a message stating the actual length and the limit so the agent can summarize and retry.

There is no search_context. Grep over a small markdown folder is enough, and agents already have it.

Safety

Every path is resolved through a single guard; nothing outside ai_context/ is ever read or written, and traversal in a slug or topic is rejected rather than quietly sanitized into something else.
Writes go to a temp file and are renamed into place, so a crash cannot leave a half-written file.
No state between calls, no caches. Edits from a human, a git pull or another agent are picked up on the next call.

Development

npm install
npm test          # unit + stdio integration tests
npm run typecheck # sources and tests
npm run build

License

MIT

Available Tools

5 tools

get_contextGet project contextA

Read-only

Read the project's persistent AI context: index, project description, constraints, decisions, plans, memory. Call with no arguments at session start to orient yourself.

ParametersJSON Schema

Name	Required	Description	Default
`topic`	No	What to read. One of "index" (default, the table of contents), "project", "constraints", "memory", "decisions" (list only), "plans" (list only), a decision ID like "0003", or a plan slug.

TDQS

A4.4/5.0

Behavior3/5

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

Annotations declare readOnlyHint=true and openWorldHint=false, so the description does not repeat that. It adds context about the content being 'persistent' and that 'index' is the default topic, which is useful. However, it does not disclose details like what happens if a topic is not found, or the exact format of the response (e.g., plain text vs JSON). Since annotations already cover safety, a 3 is appropriate—description adds some value but lacks behavioral depth beyond the schema.

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?

The description is two sentences: the first lists what the tool reads, the second gives a clear usage instruction. No fluff, every word earns its place. It front-loads the purpose and immediately follows with actionable guidance, making it highly scannable for an AI agent.

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

Completeness4/5

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

Given the simplicity (single optional parameter, no output schema, benign read operation), the description is nearly complete. It explains the tool's role and how to invoke it. However, it could mention what happens with a specific decision ID (like returns that decision) but that is implied. The lack of output schema means the description should hint at the format, but since the schema already covers parameters, this is still rated high.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema already documents each topic value. The description adds a little by mentioning 'index' as default and that 'decisions' and 'plans' are list-only, which is not in the schema. It also explains the purpose of the parameter ('What to read'). Since schema does the heavy lifting, a 3 is baseline, but the extra specification of list-only and default raises it to 4.

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?

The description clearly states the tool reads the project's persistent AI context and lists the specific content types (index, project description, constraints, decisions, plans, memory). It distinguishes itself from siblings like record_note and record_decision by emphasizing it is a read operation, and it differentiates from list_context by targeting specific context areas. The verb 'Read' plus the resource 'persistent AI context' is specific and actionable.

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

Usage Guidelines5/5

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

The description explicitly instructs to call with no arguments at session start to orient, which is a clear when-to-use guideline. It also implies that for listing all context, you might use list_context, but it does not explicitly exclude alternatives. However, the instruction to use at session start is a strong usage signal, and the sibling list_context likely covers the 'when not' implicitly. The guidance is clear and actionable.

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

list_contextList context filesA

Read-only

List all files in the project's ai_context folder with sizes and dates.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`files`	Yes	Every file under ai_context/, empty when the folder does not exist yet.

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, and the description is fully consistent with that. It adds useful behavioral context by specifying the scoped folder and that sizes and dates are included, which helps the agent know what to expect beyond the annotation.

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?

The description is a single, clearly worded sentence that immediately states the action, target, and output contents. No wasted words.

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

Completeness5/5

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

For a zero-parameter, read-only listing tool with an output schema available, the description is complete. It names the exact folder and the output attributes, and the annotations plus output schema cover the remaining context.

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

Parameters4/5

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

There are zero parameters, so the schema provides no burden for the description to explain. Baseline of 4 is appropriate because no parameter semantics are needed.

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?

The description uses a specific verb ('List') and resource ('all files in the project's ai_context folder') and adds output details ('with sizes and dates'). This clearly distinguishes it from sibling tools like get_context, which likely retrieves a single file, and record_note/record_decision, which are write operations.

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

Usage Guidelines4/5

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

The description clearly indicates the tool is for listing all context files in a specific folder, which implies its use when an overview is needed. It does not explicitly mention when not to use it or name alternatives, but the context is clear enough for the simple listing case.

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

record_decisionRecord a decisionA

Record an architectural or otherwise important project decision as a permanent ADR. Call this whenever you make or the user confirms a significant technical choice.

ParametersJSON Schema

Name	Required	Description
`title`	Yes	Short decision title, max 80 chars.
`context`	Yes	Why this came up — forces and constraints. Max 1200 chars.
`decision`	Yes	What was decided, stated plainly. Max 1200 chars.
`supersedes`	No	ID of a decision this replaces, e.g. "0003". Must already exist.
`consequences`	Yes	What this makes easier or harder afterwards. Max 1200 chars.

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Zero-padded decision ID.
`path`	Yes	Path of the new ADR, relative to the project root.

TDQS

A4.2/5.0

Behavior4/5

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

The description adds behavioral context beyond the annotations by specifying that the record is 'permanent' and an 'ADR', implying immutability and a formal structure. It does not enumerate side effects, but this is sufficient given the write intent and non-destructive annotation.

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?

The description is extremely concise—two sentences that cover purpose and usage—with no redundancy or filler. It front-loads the key action and includes a clear trigger condition.

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

Completeness4/5

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

The description provides sufficient context for the tool's role (permanent ADR storage) and when to invoke it, and combined with the detailed schema, it gives a complete picture for the simple use case. It does not mention return values or errors, but that is not required given the lack of an output schema.

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

Parameters3/5

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

The input schema already provides detailed descriptions for each parameter (e.g., 'Short decision title, max 80 chars.'), and the tool description does not add additional semantic meaning to the parameters. Thus, it meets the baseline for schema coverage without enhancing 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?

The description clearly states that the tool records architectural or important project decisions as permanent ADRs, and specifies when to call it (upon making or confirming a significant technical choice). This distinguishes it from sibling tools like record_note and update_plan.

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

Usage Guidelines4/5

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

The description provides a clear trigger condition ('Call this whenever you make or the user confirms a significant technical choice'), which guides usage. It does not explicitly contrast with record_note, but the phrasing implies a decision-specific use case, making the guidance effective.

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

record_noteRecord a noteA

Persist a short project note: a gotcha, convention, learning, or todo that future sessions should know.

ParametersJSON Schema

Name	Required	Description	Default
`content`	Yes	The note itself, one sentence or two. Max 500 chars.
`category`	Yes	Which section of memory.md the note belongs in.

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Path of memory.md, relative to the project root.
`category`	Yes	The section the note was filed under.
`duplicate`	Yes	True when an identical note already existed and nothing was written.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations are not contradictory: readOnlyHint=false, openWorldHint=false, destructiveHint=false. The description conveys a write operation but doesn't discuss overwriting, updates, or whether existing entries get merged. It adds the intended persistence context, which annotations alone would not provide.

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?

One sentence, 3 clauses, completely dense, no filler. Packs a lot of informational words: resource, content categories, purpose. Well-formatted and front-loaded.

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

Completeness4/5

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

There is an output schema, a simple model, and sibling tools that create no ambiguity. The description doesn't explain all edge cases like duplicates or retention policy, but with full schema and a single-purpose persist tool this reaches the high end of viable.

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

Parameters4/5

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

The schema covers both params (content, category) at 100% coverage with descriptions. The 'category' description specifies which memory section it belongs to, and 'content' adds length/format limits. Description here slightly enriches the schema on intended use.

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 uses the specific verb 'persist' with the resource 'project note' and lists note types (gotcha, convention, learning, todo), distinguishing it from sibling tools that manage context, decisions, plans, or context lists. It does not explicitly name alternative tools or when-not conditions.

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

Usage Guidelines4/5

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

The description states the note should be remembered by future sessions, implying cross-session persistence. It doesn't mention when to prefer this over alternatives, but the category and memory intent provide clear context.

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

update_planCreate or overwrite a planA

DestructiveIdempotent

Create or fully overwrite a named project plan. Plans are mutable working documents, unlike decisions.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes	Plan name; slugified for the filename. Max 50 chars of slug.
`content`	Yes	Full markdown body — this replaces the file. Max 8000 chars.

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Path of the plan, relative to the project root.
`slug`	Yes	Slug the plan is stored under.
`created`	Yes	True for a new plan, false when an existing one was replaced.

TDQS

A4.1/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description's 'fully overwrite' confirms this but adds no major new behavioral detail beyond the 'mutable working documents' framing. With annotations present, the added value is modest.

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?

A single sentence that is front-loaded with the core action and includes a meaningful comparison. No filler or redundant content.

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

Completeness5/5

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

With complete parameter schema, annotations covering destructive/idempotent behavior, an output schema present, and sibling differentiation, the description is sufficient for a simple two-parameter tool. Nothing critical is missing.

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

Parameters3/5

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

Schema description coverage is 100%, with detailed explanations for both parameters including slugification and file replacement. The description itself adds no parameter-level semantics, so the baseline score of 3 applies.

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?

The description uses a specific verb and resource ('Create or fully overwrite a named project plan') with clear scope. It also differentiates from siblings by contrasting plans with decisions.

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

Usage Guidelines4/5

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

The description provides context that plans are mutable working documents 'unlike decisions', indicating when this tool should be used over the decision-recording alternative. It does not explicitly enumerate all sibling alternatives or state when not to use it for other tools.

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.

5 tool updatesv0.1.0Aug 21, 2026
- First observedget_context
- First observedlist_context
- First observedrecord_decision
- First observedrecord_note
- First observedupdate_plan

Install Server

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

TDQS

A4.3/5.0

Disambiguation4/5

Each tool targets a distinct action: reading full context, listing files, recording a note, recording a decision, and updating a plan. The only potential overlap is between get_context and list_context, but their descriptions clearly differentiate content retrieval from file listing.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (get_context, record_note, record_decision, update_plan, list_context) using snake_case. The verbs are descriptive and the pattern is uniform across the set.

Tool Count5/5

With 5 tools, the server is well-scoped for managing AI context. Each tool serves a clear purpose without redundancy, and the count is appropriate for the narrow domain.

Completeness4/5

The set covers the core workflow: reading the full context, listing stored files, and writing notes, decisions, and plans. Minor gaps exist (e.g., no direct note or decision deletion/editing), but these are acceptable given the 'permanent' nature of decisions and the mutable plan overwrite capability.

Maintenance

ActivityMaintained

ResponsivenessNo issues

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

Agentage MemoryOAuth
io.agentage
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Knowledge & Memory File Systems
2
hjarni AOAuth
com.hjarni
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Note Taking Workplace & Productivity
3
cortexpad A
com.cortexpad
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Note Taking Knowledge & Memory
162
TaprootOAuth
com.taproothq
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Knowledge & Memory Note Taking
2

Related MCP Servers

Engram
Knowledge & Memory Note Taking
rwnalds
A
license
A
quality
A
maintenance
A self-hosted MCP server that gives AI agents shared, long-term memory over a git-backed folder of markdown, enabling persistent knowledge search, read, and write without a database.
Updated 23 days ago (2026-08-14 12:09 UTC)
16
21
11
MIT
Jarvis Markdown MCP
Knowledge & Memory File Systems Developer Tools
ash25082003
A
license
B
quality
B
maintenance
Local-first memory server for AI coding agents that stores work sessions, tasks, and durable memories in Markdown files, exposed through MCP tools for session management and memory retrieval.
Updated 23 days ago (2026-08-14 16:38 UTC)
10
13
1
MIT
SecondBrain
Knowledge & Memory RAG Systems Note Taking
no-carve-only-pizza
A
license
A
quality
C
maintenance
A local-first MCP server that provides a shared Markdown-based memory for AI coding agents, enabling cross-agent context persistence via tools like memory_search and memory_capture.
Updated a month ago (2026-08-10 21:34 UTC)
10
1
MIT
agent-postit
Note Taking Knowledge & Memory
gerelef
A
license
A
quality
B
maintenance
A local MCP server that provides AI agents with persistent sticky-note memory, storing Markdown notes on disk and offering tools for creating, reading, updating, deleting, searching, and listing notes across sessions.
Updated a month ago (2026-08-04 10:45 UTC)
13
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/gkrisz22/ai_context'

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