|
| 1 | +--- |
| 2 | +name: gitmem |
| 3 | +description: Institutional memory for AI agents via MCP. Gives your agent persistent memory that survives across sessions — mistakes (scars), successes (wins), decisions, and open threads. Use when you want your agent to stop repeating the same mistakes, carry context between sessions, and learn from experience. Not chat history — earned knowledge. |
| 4 | +homepage: https://gitmem.ai |
| 5 | +metadata: '{"openclaw":{"emoji":"🧠","requires":{"bins":["npx"],"env":[]},"os":["darwin","linux","win32"]}}' |
| 6 | +user-invocable: true |
| 7 | +--- |
| 8 | + |
| 9 | +# GitMem — Institutional Memory for AI Agents |
| 10 | + |
| 11 | +Your agent starts from zero every session. GitMem fixes that. |
| 12 | + |
| 13 | +It's an MCP server that gives your agent **persistent memory across sessions** — not chat history, but *earned knowledge*: mistakes to avoid, approaches that worked, architectural decisions, and unfinished work. |
| 14 | + |
| 15 | +## Setup |
| 16 | + |
| 17 | +### 1. Add the MCP server |
| 18 | + |
| 19 | +```bash |
| 20 | +openclaw mcp add gitmem -- npx -y gitmem-mcp |
| 21 | +``` |
| 22 | + |
| 23 | +Or add manually to `~/.openclaw/mcp.json`: |
| 24 | + |
| 25 | +```json |
| 26 | +{ |
| 27 | + "mcpServers": { |
| 28 | + "gitmem": { |
| 29 | + "command": "npx", |
| 30 | + "args": ["-y", "gitmem-mcp"] |
| 31 | + } |
| 32 | + } |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +### 2. Initialize in your project |
| 37 | + |
| 38 | +```bash |
| 39 | +cd your-project |
| 40 | +npx gitmem-mcp init |
| 41 | +``` |
| 42 | + |
| 43 | +The wizard creates: |
| 44 | +- `.gitmem/` directory with 3 starter scars |
| 45 | +- Memory protocol instructions for your agent |
| 46 | +- Lifecycle hooks for automatic session management |
| 47 | + |
| 48 | +Already have config? The wizard merges without destroying anything. Re-running is safe. |
| 49 | + |
| 50 | +## How It Works |
| 51 | + |
| 52 | +``` |
| 53 | +recall → work → learn → close → recall → ... |
| 54 | +``` |
| 55 | + |
| 56 | +1. **Recall** — Before acting, the agent checks memory for relevant lessons |
| 57 | +2. **Work** — The agent applies past lessons automatically |
| 58 | +3. **Learn** — Mistakes become scars, successes become wins |
| 59 | +4. **Close** — Session reflection persists context for next time |
| 60 | + |
| 61 | +## What Gets Remembered |
| 62 | + |
| 63 | +| Type | Purpose | Example | |
| 64 | +|------|---------|---------| |
| 65 | +| **Scars** | Mistakes to avoid | "Always validate UUID format before DB lookup" | |
| 66 | +| **Wins** | Approaches that worked | "Parallel agent spawning cut review time by 60%" | |
| 67 | +| **Patterns** | Reusable strategies | "5-tier test pyramid for MCP servers" | |
| 68 | +| **Decisions** | Architectural choices + rationale | "Chose JWT over session cookies for stateless auth" | |
| 69 | +| **Threads** | Unfinished work across sessions | "Rate limiting still needs implementation" | |
| 70 | + |
| 71 | +Every scar includes **counter-arguments** — reasons why someone might reasonably ignore it. This prevents memory from becoming rigid rules. |
| 72 | + |
| 73 | +## Tools Reference |
| 74 | + |
| 75 | +Once the MCP server is running, your agent gets these tools: |
| 76 | + |
| 77 | +| Tool | When to use | |
| 78 | +|------|-------------| |
| 79 | +| `recall` | Before any task — surfaces relevant warnings from past experience | |
| 80 | +| `confirm_scars` | After recall — acknowledge each scar as APPLYING, N_A, or REFUTED | |
| 81 | +| `search` | Explore institutional knowledge by topic | |
| 82 | +| `log` | Browse recent learnings chronologically | |
| 83 | +| `session_start` | Beginning of session — loads context and open threads | |
| 84 | +| `session_close` | End of session — persists what you learned | |
| 85 | +| `create_learning` | Capture a mistake (scar), success (win), or pattern | |
| 86 | +| `create_decision` | Log an architectural or operational decision | |
| 87 | +| `list_threads` | See unresolved work carrying over between sessions | |
| 88 | +| `create_thread` | Track something that needs follow-up later | |
| 89 | + |
| 90 | +## How This Differs from OpenClaw's Built-in Memory |
| 91 | + |
| 92 | +OpenClaw's native memory tracks **what was said** — conversation history, user preferences, context. |
| 93 | + |
| 94 | +GitMem tracks **what was learned** — earned lessons from things that broke, decisions and their rationale, approaches that worked and why. It's the difference between remembering a conversation and remembering the lesson from it. |
| 95 | + |
| 96 | +They complement each other: |
| 97 | + |
| 98 | +| | OpenClaw Memory | GitMem | |
| 99 | +|---|----------------|--------| |
| 100 | +| **Scope** | Conversational context | Institutional knowledge | |
| 101 | +| **Loaded** | Automatically every turn | On-demand via recall | |
| 102 | +| **Best for** | Preferences, history | Lessons, decisions, patterns | |
| 103 | +| **Updates** | Continuous | Session ceremonies | |
| 104 | +| **Example** | "User prefers Python" | "Always run migrations with --dry-run first" | |
| 105 | + |
| 106 | +## Example Session |
| 107 | + |
| 108 | +``` |
| 109 | +Agent: [session_start] Loading context... |
| 110 | + 2 open threads, 15 scars in memory. |
| 111 | +
|
| 112 | +You: "Add caching to the API" |
| 113 | +
|
| 114 | +Agent: [recall plan="implement caching layer"] |
| 115 | + ⚠ Scar: "Cache invalidation caused stale data bug — always set TTL" |
| 116 | + ⚠ Scar: "Redis connection pooling required in containerized deploys" |
| 117 | + [confirm_scars] APPLYING both — using TTL and connection pool. |
| 118 | +
|
| 119 | + ... implements caching with TTL and pooling ... |
| 120 | +
|
| 121 | +You: "done for today" |
| 122 | +
|
| 123 | +Agent: [session_close] |
| 124 | + Reflection: |
| 125 | + - What worked: Redis caching with TTL pattern |
| 126 | + - New scar: "Cache key collisions between services — namespace keys" |
| 127 | + - Open thread: "Cache warming strategy still TBD" |
| 128 | +``` |
| 129 | + |
| 130 | +## CLI Commands |
| 131 | + |
| 132 | +| Command | Description | |
| 133 | +|---------|-------------| |
| 134 | +| `npx gitmem-mcp init` | Interactive setup wizard | |
| 135 | +| `npx gitmem-mcp init --yes` | Non-interactive setup | |
| 136 | +| `npx gitmem-mcp init --dry-run` | Preview changes | |
| 137 | +| `npx gitmem-mcp check` | Diagnostic health check | |
| 138 | +| `npx gitmem-mcp uninstall` | Clean removal (preserves data) | |
| 139 | + |
| 140 | +## Links |
| 141 | + |
| 142 | +- **Docs**: https://gitmem.ai/docs |
| 143 | +- **npm**: https://www.npmjs.com/package/gitmem-mcp |
| 144 | +- **GitHub**: https://github.com/gitmem-dev/gitmem |
| 145 | +- **Getting Started**: https://gitmem.ai/docs/getting-started |
0 commit comments