npm run setup

cp -r release/ ~/.contextforge/
chmod +x ~/.contextforge/contextforge

Step 1: Capture          Step 2: Extract            Step 3: Query
┌──────────────┐       ┌────────────────────┐     ┌───────────────────┐
│ Agent talks   │──────▶│ Extractor pulls    │────▶│ Graph DB stores   │
│ to user       │       │ entities, facts,   │     │ only structured   │
│ (50-200KB)    │       │ relations          │     │ knowledge (2-5KB) │
└──────────────┘       └────────────────────┘     └───────────────────┘
                              │                          │
                              ▼                          ▼
                     Raw text DISCARDED          Graph is queryable
                                                 across all projects

{
  "servers": {
    "contextforge": {
      "command": "/Users/<username>/.contextforge/contextforge",
      "type": "stdio"
    }
  }
}

{
  "contextforge": {
    "type": "stdio",
    "command": "/Users/<username>/.contextforge/contextforge",
    "args": []
  }
}

{
  "servers": {
    "contextforge": {
      "type": "stdio",
      "command": "/Users/<username>/.contextforge/contextforge",
      "args": []
    }
  }
}

claude mcp add --transport stdio --scope project contextforge -- /Users/<username>/.contextforge/contextforge

---
description: "Use when: starting any conversation, recalling past work, ending a conversation. Manages persistent memory across all workspaces using the contextforge MCP tools."
---

# ContextForge

You have access to a persistent knowledge graph via MCP tools that remembers context across all conversations and workspaces.

## At the start of every conversation

1. Call `get_workspace_context` with the current workspace path to load known entities, decisions, patterns, and facts from past conversations.
2. Use this context to avoid re-asking questions the user already answered, and to build on past decisions.

## During the conversation

- When the user asks about past work, decisions, or patterns, call `search_memory` to find relevant entities.
- When the user asks to refer to a Rally ticket (for example `US12345` or `TF6789`), call `get_rally_work_item` to fetch the latest details from Rally.
- When a notable decision, pattern, or convention is established, call `add_fact` to persist it immediately.

## At the end of a meaningful conversation

- When significant work was done (code changes, architectural decisions, bug fixes, new patterns), call `save_conversation` with the workspace path and the conversation messages.
- This extracts entities, relationships, and facts into the graph. Raw text is discarded.
- Skip this for trivial questions or one-off lookups.

## Tool summary

| Tool | When to use |
|------|-------------|
| `get_workspace_context` | Start of conversation — load past knowledge |
| `search_memory` | Recall past work, decisions, errors, patterns |
| `add_fact` | Persist a decision, convention, or insight immediately |
| `get_rally_work_item` | Fetch live Rally details for TF/US references |
| `save_conversation` | End of meaningful conversation — extract and store knowledge |
| `memory_status` | Check how much is stored, which workspaces have data |
| `cleanup_memory` | Remove old knowledge by time range (optionally per workspace) |
| `forget_workspace` | Completely remove all knowledge for a workspace |

# Install the VSIX from the release folder
code --install-extension release/contextforge-capture-0.1.0.vsix

                    WRITE PATH                              READ PATH
                    ──────────                              ─────────
┌──────────────────────────────────┐          ┌──────────────────────────────────┐
│  Capture Extension (in IDE)      │          │  Agent (in IDE)                  │
│                                  │          │                                  │
│  Watches chat sessions,          │          │  MCP resource auto-injected      │
│  extracts messages,              │          │  into context on start.          │
│  writes to inbox.                │          │  MCP tools called on demand.     │
│  (VS Code extension)            │          │                                  │
└─────────────┬────────────────────┘          └───────────────┬──────────────────┘
              │                                               │
              ▼                                               │
    ~/.contextforge/inbox/                                    │
    (JSON files: sessionId,                                   │
     workspace, messages)                                     │
              │                                               │
              ▼                                               ▼
         ┌──────────────────────────────────────────────────────────┐
         │                  MCP Server (contextforge binary)        │
         │                                                          │
         │  On startup + before reads: processInbox()               │
         │    → parse inbox JSON → extract knowledge → ingest       │
         │                                                          │
         │  Tools (8): search_memory, get_workspace_context,        │
         │    save_conversation, add_fact, get_rally_work_item,     │
         │    memory_status, cleanup_memory, forget_workspace       │
         │                                                          │
         │  Resource: contextforge://workspace/{path}               │
         │    → auto-injected into agent context                    │
         │                                                          │
         │  ┌──────────────┐  ┌──────────────┐                     │
         │  │ Extractor    │  │MemoryDatabase│                     │
         │  │ (no LLM)    │  │ (SQLite)     │                     │
         │  └──────────────┘  └──────┬───────┘                     │
         └───────────────────────────┼─────────────────────────────┘
                                     │
                                     ▼
                           ~/.contextforge/contextforge.db

┌─────────────────────────────────────┐
│  1. User chats with Copilot in IDE  │
│     (VS Code)                       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  2. IDE writes session to disk      │
│     chatSessions/<id>.jsonl         │
│     (JSONL event log format)        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  3. Capture Extension detects       │
│     change via FileSystemWatcher    │
│     (30-second debounce)            │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  4. Extension parses JSONL,         │
│     extracts messages, writes       │
│     JSON to inbox                   │
│     ~/.contextforge/inbox/          │
│       session-<id>-<ts>.json        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  5. MCP Server processInbox()       │
│     runs on startup + before        │
│     each resource read              │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  6. Extractor (rule-based, no LLM)  │
│     extracts entities, relations,   │
│     facts from messages             │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  7. SQLite Database                 │
│     ~/.contextforge/contextforge.db       │
│     Entities, Facts, Relations      │
│     stored permanently              │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  1. New conversation starts         │
│     IDE auto-reads MCP resource     │
│     contextforge://workspace/...    │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  2. MCP Server queries SQLite DB   │
│     Returns entities, facts,        │
│     relationships for workspace     │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  3. Knowledge injected into agent   │
│     context — agent sees past       │
│     decisions, patterns, errors     │
│     before first user message       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  4. During conversation, agent      │
│     calls search_memory, add_fact   │
│     on demand via MCP tools         │
└─────────────────────────────────────┘

{
  "sessionId": "abc123-...",
  "workspace": "/Users/you/src/my-project",
  "title": "Fix auth middleware bug",
  "messages": [
    { "role": "user", "content": "The login endpoint returns 401..." },
    { "role": "assistant", "content": "The JWT expiry check in auth.ts..." }
  ],
  "capturedAt": 1776885043000
}

URI template: contextforge://workspace/{workspace_path}

-- "What do we know about auth.ts?"
MATCH (e:Entity {name: 'auth.ts'})-[r:RELATES_TO]->(related:Entity)
RETURN e, r, related

-- "What libraries does the project use?"
MATCH (e:Entity {type: 'library', workspace: '/my/project'})
RETURN e.name

-- "What errors have been fixed?"
MATCH (err:Entity {type: 'error'})-[r:RELATES_TO {type: 'fixed_by'}]->(fix:Entity)
RETURN err.name, fix.name

-- "Everything about JWT" (2-hop traversal)
MATCH (e:Entity)-[*1..2]-(related:Entity)
WHERE e.name CONTAINS 'JWT'
RETURN e, related

User says: "fix login bug"
                 │
Graph resolves:  "login" → login.ts → auth.ts → JWT expiry bug → fix applied
                 (traverses relationships, not keyword matching)

┌─────────────────────────────────────┐
│  1. User asks:                      │
│     "Why did we choose JWT?"        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  2. Agent parses intent             │
│     Keyword: JWT                    │
│     Intent: decision / reason       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  3. Agent calls search_memory       │
│     query='JWT', depth=2, limit=20  │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  4. mcp.ts search_memory handler    │
│     Builds GraphQuery:              │
│     entityName = 'JWT'              │
└──────────────┬──────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────┐
│  database.ts → query()                                   │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Step 1: Find root entities                        │  │
│  │  MATCH (e:Entity)                                  │  │
│  │  WHERE e.name CONTAINS 'JWT'                       │  │
│  │  ORDER BY e.updatedAt DESC                         │  │
│  │  LIMIT 20                                          │  │
│  │                                                    │  │
│  │  Matches:                                          │  │
│  │    [library]  JWT                                  │  │
│  │    [decision] JWT instead of sessions              │  │
│  │    [error]    JWT expiry bug                       │  │
│  └────────────────┬───────────────────────────────────┘  │
│                   │                                      │
│                   ▼                                      │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Step 2: Walk relationships (depth=2)              │  │
│  │  For each root entity:                             │  │
│  │  MATCH (a)-[r:RELATES_TO*1..2]->(b)               │  │
│  │  WHERE a.id = rootId                               │  │
│  │                                                    │  │
│  │  Discovers connected entities:                     │  │
│  │    auth.ts, jsonwebtoken, login.ts,                │  │
│  │    auth.test.ts ...                                │  │
│  └────────────────┬───────────────────────────────────┘  │
│                   │                                      │
│                   ▼                                      │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Step 3: Get direct relations                      │  │
│  │  Between all found entity IDs:                     │  │
│  │  MATCH (a)-[r:RELATES_TO]->(b)                     │  │
│  │                                                    │  │
│  │    auth.ts      --uses-->       JWT                │  │
│  │    auth.test.ts --tests-->      auth.ts            │  │
│  │    error        --caused_by-->  auth.ts            │  │
│  └────────────────┬───────────────────────────────────┘  │
│                   │                                      │
│                   ▼                                      │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Step 4: Get facts                                 │  │
│  │  For each entity ID:                               │  │
│  │  MATCH (e)-[:HAS_FACT]->(f)                        │  │
│  │                                                    │  │
│  │  decision entity →                                 │  │
│  │    key   = 'reason'                                │  │
│  │    value = 'scales better than sessions'           │  │
│  └────────────────┬───────────────────────────────────┘  │
└───────────────────┼──────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────┐
│  5. mcp.ts formats GraphResult      │
│     into text response:             │
│                                     │
│  [library] JWT (/my/project)        │
│  [decision] JWT instead of sessions │
│    reason: scales better            │
│                                     │
│  Relationships:                     │
│    auth.ts --uses--> JWT            │
│    auth.test.ts --tests--> auth.ts  │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  6. Agent synthesizes answer:       │
│     "We chose JWT over sessions     │
│      because it scales better.      │
│      It's used in auth.ts."         │
└─────────────────────────────────────┘

~/.contextforge/
├── contextforge              # MCP server binary
├── contextforge.db                 # SQLite database (all workspaces, all IDEs)
├── models/                   # ONNX embedding model (optional, for vector search)
│   └── Xenova/all-MiniLM-L6-v2/
├── inbox/                    # Conversations queued by capture extensions
│   ├── <session-id>.json     # Pending conversations (processed on next MCP call)
│   └── .processed            # Log of already-processed session IDs
└── node_modules/             # Native addons
    └── better-sqlite3/       # SQLite native binding

# Agent instructions (VS Code / Cursor)
~/Library/Application Support/Code/User/prompts/
└── contextforge.instructions.md   # Tells agents to use memory tools automatically

# MCP config (VS Code / Cursor)
~/Library/Application Support/Code/User/mcp.json

# Simply copy the database file
cp ~/.contextforge/contextforge.db ~/backup/contextforge.db

# Delete the database and start fresh
rm -rf ~/.contextforge/contextforge.db
# The next MCP tool call will create a new empty database

agent-plugin-optimize-prompt-history/
├── package.json                         # Root workspace config
├── tsconfig.base.json                   # Shared TypeScript config
├── packages/
│   ├── core/                            # MCP server + graph engine
│   │   ├── src/
│   │   │   ├── index.ts                 # Public API exports
│   │   │   ├── models.ts               # TypeScript types (Entity, Relation, Fact, etc.)
│   │   │   ├── schema.ts               # SQLite schema initialization (tables, indexes, FTS5, vec0)
│   │   │   ├── database.ts             # MemoryDatabase — SQLite wrapper with graph-like queries
│   │   │   ├── extractor.ts            # Rule-based knowledge extraction
│   │   │   ├── mcp.ts                  # MCP stdio server (entry point for binary)
│   │   │   └── __tests__/
│   │   │       └── extractor.test.ts   # Unit tests for extraction (7 tests)
│   │   ├── build.js                     # Build pipeline (esbuild → obfuscate → pkg → release)
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── vscode-extension/                # VS Code capture extension
│   │   ├── src/
│   │   │   ├── extension.ts             # Main entry point, command registration
│   │   │   ├── capture.ts              # Chat session file watcher + debounced capture
│   │   │   ├── sessionParser.ts        # JSONL event log parser for Copilot Chat sessions
│   │   │   ├── chatParticipant.ts      # @memory chat participant (manual save/search/status)
│   │   │   ├── inbox.ts               # Writes to ~/.contextforge/inbox/ queue
│   │   │   └── statusBar.ts           # Status bar integration
│   │   └── package.json                 # Extension manifest with contributions