yaad

The Problem

Every coding agent forgets everything when the session ends.

Session 1: You explain your stack, conventions, architecture. Agent writes great code.
Session 2: Agent has forgotten everything. You start over.
Session 50: You've wasted hours re-teaching the same context.

The Fix

Add one line to your agent's MCP config:

{ "mcpServers": { "yaad": { "command": "yaad", "args": ["mcp"] } } }

Now your agent remembers everything — across sessions, across models, across projects.

30-Second Setup

# Install
curl -fsSL https://raw.githubusercontent.com/GrayCodeAI/yaad/main/install.sh | sh

# Add to your project
cd your-project && yaad init

# Connect your agent
yaad setup hawk          # or any of 23 supported agents

That's it. Your agent now has persistent, graph-native memory.

What Happens Next

Your agent starts a session → Yaad injects context from previous sessions:

## Project Memory (Yaad)

### Conventions (always follow)
- Use `jose` library, not `jsonwebtoken` (Edge compatibility)
- Named exports only, no default exports
- Run `pnpm test --coverage` before committing

### Active Tasks
- ✓ JWT token issuance endpoint
- → Rate limiting on /auth/token (in progress)

### ⚠ Stale Warnings
- Auth subgraph outdated: src/middleware/auth.ts modified 2h ago

### Previous Session
- Implemented rate limiting skeleton, hit NATS backpressure issue

Your agent works → stores decisions, bugs, conventions automatically.
Session ends → Yaad compresses and links everything in a memory graph.
Next session → picks up exactly where you left off. Zero re-explaining.

Supported Agents

Yaad works with any coding agent that supports MCP or HTTP.

How It Works

Yaad is a memory layer — it doesn't call LLMs. Your agent handles the LLM. Yaad handles memory.

Your Agent                          Yaad
   │                                  │
   ├─ starts session ──────────────▶  │ returns hot-tier context (~2K tokens)
   │                                  │
   ├─ needs context ───────────────▶  │ graph-aware search (BM25 + vector + graph + temporal)
   │  "auth middleware"               │ returns: decisions + conventions + bugs + specs
   │                                  │
   ├─ learns something ────────────▶  │ stores node, extracts entities, links edges
   │  "Use RS256 for JWT"            │ auto-detects: file refs, libraries, functions
   │                                  │
   ├─ ends session ────────────────▶  │ compresses → summary node → links to graph
   │                                  │
   └─ next session ────────────────▶  │ picks up from summary. zero re-explaining.

Under the Hood

Relaxed DAG — memories are nodes, relationships are edges:

[decision: "Use RS256"] ──led_to──▶ [convention: "Always RS256"]
        │                                     │
        │ led_to                              │ touches
        ▼                                     ▼
[spec: "Auth subsystem"] ◀──part_of── [file: src/middleware/auth.ts]
        │
        │ relates_to
        ▼
[bug: "Token refresh race"] ──supersedes──▶ [bug: "Token expiry (FIXED)"]

Intent-aware retrieval — "why" queries traverse causal edges, "when" queries traverse temporal edges:

"why did we choose NATS?"  → Intent: Why  → boost caused_by, led_to edges
"when did we fix auth?"    → Intent: When → boost temporal backbone
"what is the auth spec?"   → Intent: What → boost spec, part_of edges

4-path search — BM25 + vector + graph (intent-aware) + temporal recency, fused with RRF.

Memory Types

Key Features

yaad sync                    # export chunk + import teammates' chunks
git add .yaad/manifest.json .yaad/chunks/
git push

Architecture

┌─────────────────────────────────────────────────────────────────┐
│              ANY CODING AGENT                                   │
│  Hawk · Claude Code · Cursor · Gemini CLI · OpenCode · Any     │
└──────┬───────────────┬──────────────────────────┬───────────────┘
       │ MCP (stdio)   │ REST/HTTPS (:3456)       │ gRPC (:3457)
       ▼               ▼                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                       YAAD                                      │
│  Memory Engine · Graph Engine · 4-Path Search · Dual-Stream     │
├─────────────────────────────────────────────────────────────────┤
│  SQLite (pure Go, no CGO) · FTS5 · Embeddings (optional)       │
└─────────────────────────────────────────────────────────────────┘

18MB binary. Zero dependencies. Pure Go. No C compiler. No Docker. No cloud.

Troubleshooting

yaad doctor    # diagnose setup issues (DB, server, MCP config, git)

Documentation

Community

• Discord: GrayCodeAI
• Issues: GitHub Issues
• Contributing: CONTRIBUTING.md