Sentinel-Memory MCP

A lightweight MCP server that records and reuses Prompt Gaps — essential context missing from initial instructions — so your AI assistant learns from every session.

No vector databases. No ML models. Just a plain JSONL file tracked by Git.

---

How It Works

Every time your AI assistant works on a task, it encounters information that was never in the original instructions but turned out to be critical. Sentinel-Memory captures those gaps and surfaces them automatically at the start of the next related task.

[Before task]  search_memory()        →  past lessons + questions to ask
[After task]   log_memory()           →  what was missing, what to remember
[When full]    compact_memory()       →  group logs by topic for Claude to summarize
               compact_memory_delete() →  remove originals after principle is saved

Memory is stored in .context/memory_log.jsonl inside your project — a plain text file you can read, diff, and commit like any other source file.

---

Features

• Zero ML dependencies — no embeddings, no model downloads
• Git-native storage — plain JSONL, human-readable, fully diffable
• Claude judges relevance — returns all records; Claude picks what matters
• Topic normalization — similar topics merged during compaction
• Atomic writes — temp file + rename, safe against crashes
• Cross-platform file locking — directory-based lock, works on Windows and Linux
• Sensitive data filtering — API keys and tokens redacted before storage
• npx-ready — no installation required once published to npm

---

Requirements

• Node.js 18+
• An MCP-compatible client (Cursor, Claude Code, etc.)

---

Installation

Option A — npx (after npm publish, no installation needed)

Copy .cursor/mcp.json.example to .cursor/mcp.json in your project:

{
    "mcpServers": {
        "sentinel-memory": {
            "command": "npx",
            "args": ["-y", "@vncy/sentinel-memory-mcp"]
        }
    }
}

Cursor automatically sets the working directory to the workspace root when launching MCP servers, so no cwd is needed. .context/memory_log.jsonl is created in the project root on first use.

Option B — local build

git clone https://github.com/your-org/dug-sentinel-memory-mcp.git
cd dug-sentinel-memory-mcp
npm install
npm run build

Then reference the built file directly in .cursor/mcp.json:

{
    "mcpServers": {
        "sentinel-memory": {
            "command": "node",
            "args": ["/absolute/path/to/dug-sentinel-memory-mcp/dist/server.js"]
        }
    }
}

.cursor/mcp.json is listed in .gitignore. Copy .cursor/mcp.json.example and edit locally — no need to commit your personal paths.

---

Project path per developer

Each developer keeps their own .cursor/mcp.json (git-ignored). Cursor sets the working directory to the workspace root automatically, so every developer gets their own .context/ without any path configuration.

Developer A  opens ProjectA  →  MCP CWD = ProjectA/  →  ProjectA/.context/memory_log.jsonl
Developer B  opens ProjectB  →  MCP CWD = ProjectB/  →  ProjectB/.context/memory_log.jsonl

---

Tools

search_memory(query, topic?)

Call this before starting any task. Returns all past records (filtered by topic if specified). Claude reads the output and selects relevant lessons.

Parameter	Type	Description
query	string	Task description or keywords
topic	string (optional)	Exact-match topic filter

log_memory(topic, missing_context, lesson, ask_next_time?, type?, compact_threshold?)

Call this after completing any task. Records what was missing and what to remember.

Parameter	Type	Description
topic	string	Module/feature tag (e.g. auth, payment)
missing_context	string	Info absent from original instructions but critical
lesson	string	Rule to apply in future tasks
ask_next_time	string (optional)	Question to ask the user next time
type	string (optional)	"log" (default) or "principle" (compacted)
compact_threshold	int (optional)	Compaction trigger count (default: 50)

compact_memory(target_topic?, compact_threshold?)

Call this when record count exceeds the threshold. Returns grouped records for Claude to summarize into principles.

compact_memory_delete(ids)

Call this only after log_memory(type="principle") succeeds. Deletes the original log records by id.

---

Workflow (.cursorrules)

The .cursorrules file enforces the 3-step loop for every task:

You are the Memory Manager for this project.
All tasks are grounded in .context/memory_log.jsonl.

IMPORTANT: Do NOT write any code or edit any file before completing Step 1.

[Before every task — REQUIRED]
1. Call search_memory with a description of the current task.
2. Read the returned records and identify lessons relevant to this task.
3. If relevant records exist:
   - Apply the lessons directly to your approach.
   - Ask the user the questions listed in ask_next_time before proceeding.
4. If no relevant records exist:
   - Do not guess constraints. Ask the user about key requirements first.

[After every task — REQUIRED]
5. Call log_memory with:
   - missing_context  ←  info absent from the initial instructions but turned out critical
   - lesson           ←  rule to apply in future tasks of this type
   - ask_next_time    ←  question to ask the user before starting similar tasks

[Topic naming rules]
- Use module- or feature-level granularity (language/framework agnostic).
- Good examples : auth, payment, api-gateway, ui-form, db-migration
- Too narrow (forbidden) : login_bug_fix_2026, verify_token_v2
- Too broad  (forbidden) : code, backend, fix
- Check existing topics first. Reuse a close match instead of creating a new one.
  e.g. if "auth-login" exists, use it instead of creating "authentication"

[Compaction — REQUIRED when record count exceeds 50]
6.  Call compact_memory to receive records grouped by topic.
7.  Merge similar topics (e.g. "auth", "auth-login" → "auth").
8.  Summarize each topic's lessons into one concise sentence.
9.  Merge each topic's ask_next_time values; keep under 512 bytes total.
10. Call log_memory(type="principle", ...) to store the summary.
11. After confirming the principle is saved, call compact_memory_delete(ids=[...]) to remove originals.

Skipping any step in this sequence is not allowed.

---

Data format

Records are stored one JSON object per line in .context/memory_log.jsonl.

Log record:

{
    "id": "a1b2c3d4e5f6a7b8",
    "type": "log",
    "topic": "payment",
    "missing_context": "VAT rates differ by country — not mentioned in the brief",
    "lesson": "Always check the country-specific tax rate file before modifying payment logic",
    "ask_next_time": "Which countries does this change apply to?",
    "meta": { "created": "2026-02-27T10:30:00.000Z" }
}

Principle record (after compaction):

{
    "id": "b2c3d4e5f6a7b8c9",
    "type": "principle",
    "topic": "payment",
    "missing_context": "",
    "lesson": "Payment module: verify country tax rates, keep refund API separate, PG timeout is 10s",
    "ask_next_time": "Which countries apply? Which payment gateway?",
    "meta": {
        "created": "2026-03-15T09:00:00.000Z",
        "compacted_at": "2026-03-15T09:00:00.000Z",
        "source_count": 7
    }
}

Field	Limit	On exceed
topic	64 bytes (UTF-8)	Error
missing_context	1,024 bytes (UTF-8)	Error
lesson	1,024 bytes (UTF-8)	Error
ask_next_time	512 bytes (UTF-8)	Error

---

File structure

your-project/
├── .cursor/
│   ├── mcp.json              ← git-ignored, copy from mcp.json.example
│   └── mcp.json.example      ← committed template
└── .context/
    └── memory_log.jsonl      ← auto-created, commit this file

dug-sentinel-memory-mcp/      ← this repository
├── src/
│   ├── server.ts             ← MCP tools (4 tools)
│   ├── store.ts              ← JSONL CRUD + file lock + atomic write
│   └── sanitizer.ts          ← sensitive data filter
├── dist/                     ← compiled output (generated by npm run build)
├── .cursor/
│   └── mcp.json.example      ← configuration template
├── docs/
│   ├── Design.md
│   └── Design_KR.md
├── package.json
├── tsconfig.json
├── .cursorrules
└── .gitignore

---

Security notes

• missing_context and lesson fields are scanned for API keys, tokens, and secrets before storage. Detected patterns are replaced with [REDACTED].
• .context/memory_log.jsonl is plain text. Review git diff .context/ before pushing to a shared repository.
• For sensitive projects, add .context/ to .gitignore.

---

License

MIT