Content
<div align="center">
# याद Yaad
### Give your coding agent persistent memory.
One config line. Works with any MCP agent. Zero setup.
[](LICENSE)
[](go.mod)
[](go.mod)
[](yaad_test.go)
[](https://github.com/GrayCodeAI/yaad/actions)
[](https://discord.gg/UqMbQJRE5)
</div>
---
### 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
Yaad is the **memory engine** behind the [`hawk`](https://github.com/GrayCodeAI/hawk)
coding agent. Run `hawk` and your agent gets persistent, graph-native memory — across
sessions, across models, across projects — with no separate install or daemon to manage.
> **Yaad is a Go library, not a standalone binary.** It ships no `yaad` command of its
> own; its memory features are surfaced through the host agent (hawk). To embed Yaad in
> your own Go program, import it directly:
>
> ```go
> import (
> yaad "github.com/GrayCodeAI/yaad/engine"
> "github.com/GrayCodeAI/yaad/storage"
> )
> ```
## Ecosystem Boundaries
Yaad is a Hawk support engine. Keep the dependency edge one-way:
- yaad uses local-only types (memory/retrieval types are yaad-scoped, not shared contracts)
- do not import `hawk/internal/*`
- do not import removed legacy path `hawk/shared/types`
- do not import other engines (`eyrie`, `tok`, `trace`, `sight`, `inspect`) — engines are peers, not dependencies
---
## What Happens Next
Your agent starts a session → Yaad injects context from previous sessions:
```markdown
## 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.**
---
## 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
| Type | What it stores | Example |
|---|---|---|
| `convention` | Coding rules & patterns | *"Use jose not jsonwebtoken"* |
| `decision` | Architecture choices + why | *"Chose NATS for backpressure"* |
| `bug` | Symptom → Cause → Fix | *"Token race → use mutex"* |
| `spec` | How a subsystem works | *"Auth: RS256 JWT with jose"* |
| `task` | Done / in-progress / blocked | *"✓ auth, → rate limiting"* |
| `skill` | Reusable step sequences | *"Deploy: test → build → fly"* |
| `preference` | User coding style | *"Functional style, tabs"* |
| `file` | File/module anchor | *"src/middleware/auth.ts"* |
| `entity` | Auto-extracted entity | *"jose", "PostgreSQL"* |
---
## Key Features
<details>
<summary><b>Graph-Native Memory (Relaxed DAG)</b></summary>
Not a flat list of memories. A directed graph with 8 edge types:
- **Causal** (acyclic): `led_to`, `supersedes`, `caused_by`, `learned_in`, `part_of`
- **Relational** (cycles OK): `relates_to`, `depends_on`, `touches`
Enables: subgraph extraction, impact analysis, causal chain traversal.
</details>
<details>
<summary><b>Intent-Aware 4-Path Search</b></summary>
Based on MAGMA (arxiv:2601.03236):
1. **BM25** (FTS5) — keyword matching
2. **Vector** (optional) — semantic similarity
3. **Graph** (intent-aware BFS) — edge weights boosted by query intent
4. **Temporal** — recency-aware for "when" queries
Fused with Reciprocal Rank Fusion (RRF).
</details>
<details>
<summary><b>Dual-Stream Ingestion</b></summary>
Based on MAGMA + GAM research:
- **Fast path** (sync): store node + temporal edge, return in <1ms
- **Slow path** (async goroutine): infer causal edges, link entities
Agent is never blocked waiting for memory processing.
</details>
<details>
<summary><b>Git-Aware Staleness</b></summary>
When source files change, Yaad walks the graph backwards to flag stale subgraphs:
*"Auth subgraph may be stale: src/auth.ts modified 2h ago. Affected: [decision: RS256], [convention: jose], [bug: token refresh]"*
</details>
<details>
<summary><b>Impact Analysis</b></summary>
*"What memories break if I change schema.sql?"* → reverse graph traversal → *"3 decisions + 2 specs + 1 convention affected"*
</details>
<details>
<summary><b>Auto-Decay & Compaction</b></summary>
- Half-life decay: unused memories fade automatically
- Compaction: low-confidence memories merge into summaries
- Pinned memories never decay (core architecture decisions, deploy process)
- Auto-decay runs on every session start — zero maintenance
</details>
<details>
<summary><b>Privacy & Security</b></summary>
- API keys, tokens, secrets auto-stripped on ingest (regex + entropy detection)
- Localhost-only binding (127.0.0.1)
- HTTPS with auto self-signed cert generation
- All data stays local (SQLite, your machine)
- No LLM API calls — Yaad never sends your code anywhere
</details>
<details>
<summary><b>Worktree-Aware Memory Sharing</b></summary>
Memory is scoped to the git repository root (`git rev-parse --show-toplevel`), so every worktree, subdirectory, or linked checkout of the same repo shares one `.yaad/` memory store. Falls back to the working directory when not in a git repo.
</details>
<details>
<summary><b>LLM Entity Extraction (opt-in)</b></summary>
Optionally extract entities with an OpenAI-compatible LLM, merged and deduplicated with the regex extractor. **Default off** — enable with `YAAD_LLM_EXTRACT=1` + `YAAD_LLM_API_KEY`. Falls back to regex-only on any failure, so behavior is unchanged when unset.
</details>
<details>
<summary><b>Temporal Fact-Validity Windows</b></summary>
Facts track `ValidAt` / `InvalidAt` timestamps. "When did we switch from JWT to session tokens?" traverses temporal validity windows without losing historical decision logs.
</details>
<details>
<summary><b>Atomic Fact Extraction Filter</b></summary>
Automatically parses session text and tool logs (`ingest/extract.go`) to distill raw transcripts into single-sentence conventions (`category: convention`) and decisions (`category: decision`) without requiring external LLM API calls.
</details>
<details>
<summary><b>Signed Team Memory Packs (.yaadpack)</b></summary>
Export memory graphs into portable `.yaadpack` bundles signed with HMAC-SHA256 digests (`exportimport/pack.go`). Check `.yaadpack` files into Git so every developer's agent inherits team architecture rules safely.
</details>
<details>
<summary><b>Concurrent Subagent Memory Namespaces</b></summary>
Thread-safe subagent memory isolation (`engine/namespace.go`) scopes memory nodes by `session_id:subagent_role`, allowing parallel background subagents to write memories without lock contention.
</details>
<details>
<summary><b>Louvain Community Detection</b></summary>
Hierarchical multi-level community detector (`graph/community.go`) partitions densely-connected memory nodes into modular project topic clusters.
</details>
Zep-style `valid_at` / `invalid_at` intervals on edges let recall filter to facts that were active at a given point in time, distinguishing currently-valid from superseded knowledge.
</details>
<details>
<summary><b>Live Memory Streaming (SSE; gRPC planned)</b></summary>
Remember/Forget mutations stream over HTTP/SSE at `/yaad/stream/memories`
(alias `/yaad/watch`), with stale-memory notifications at
`/yaad/stream/stale`. `WatchMemories` and `WatchStale` exist in the protobuf
design, but no gRPC server is implemented yet.
</details>
<details>
<summary><b>Versions & Rollback</b></summary>
Every edit is versioned. The engine can list a node's version history and restore a prior state — the rollback itself is recorded as a new version.
</details>
<details>
<summary><b>ADD-Only Single-Pass Mode (opt-in)</b></summary>
Mem0-v3-style single-pass ingestion that appends memories without the conflict-resolution pass. **Default off** — enable with `YAAD_ADD_ONLY=1`.
</details>
<details>
<summary><b>Subagent-Scoped Memory</b></summary>
A subagent can request its own isolated memory store (`<base>/agent-memory/<id>/`) via an agent-id env var, keeping parallel agents' memories separate.
</details>
<details>
<summary><b>Sleep-Time Consolidation (opt-in)</b></summary>
A background loop consolidates memories on the long-running `serve` / `mcp` paths. **Default off** — enable by setting `YAAD_CONSOLIDATE_INTERVAL` to a positive duration (e.g. `30m`).
</details>
<details>
<summary><b>Semantic Boundary Detection</b></summary>
Detects topic boundaries in a session to segment memories into coherent units before consolidation.
</details>
---
## Memory Tools (23 tools)
When Yaad is embedded in a host agent (such as hawk), it exposes these operations to the
agent. Yaad implements the logic; the host surfaces them (e.g. as MCP tools):
| Tool | What it does |
|---|---|
| `yaad_remember` | Store a memory (convention, decision, bug, spec, task, skill, preference) |
| `yaad_recall` | Graph-aware search with intent classification |
| `yaad_hybrid_recall` | 4-path search: BM25 + vector + graph + temporal |
| `yaad_context` | Get hot-tier context for session injection |
| `yaad_link` | Create typed edge between memories |
| `yaad_forget` | Archive a memory (sets confidence to 0) |
| `yaad_feedback` | Approve / edit / discard a memory |
| `yaad_pin` | Pin/unpin a memory (pinned = always in context) |
| `yaad_stale` | Find memories invalidated by git changes |
| `yaad_proactive` | Predict what context the agent needs next |
| `yaad_compact` | Merge low-confidence memories into summaries |
| `yaad_mental_model` | Auto-generated project summary |
| `yaad_skill_store` | Save a reusable step sequence |
| `yaad_skill_get` | Retrieve and replay a skill |
| `yaad_session_recap` | Summary of the previous session |
| `yaad_subgraph` | Extract neighborhood around a memory |
| `yaad_impact` | What memories are affected by a file change? |
| `yaad_status` | Graph stats (nodes, edges, sessions) |
| `yaad_decay` | Manually trigger confidence decay |
| `yaad_gc` | Garbage collect archived memories |
| `yaad_embed` | Generate vector embedding for a node |
| `yaad_export` | Export graph as JSON/Markdown/Obsidian |
| `yaad_import` | Import graph from JSON |
---
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ YOUR CODING AGENT │
│ Hawk · Claude Code · Cursor · Gemini CLI · Any MCP Agent │
└──────┬───────────────┬──────────────────────────────────────────┘
│ MCP (stdio) │ REST/HTTPS (127.0.0.1:3456)
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ YAAD │
│ Memory Engine · Graph Engine · 4-Path Search · Dual-Stream │
├─────────────────────────────────────────────────────────────────┤
│ SQLite (WAL mode) · FTS5 · Embeddings (optional) │
└─────────────────────────────────────────────────────────────────┘
```
**Zero dependencies. Pure Go. No CGO. No Docker. No cloud.** Embedded by the host agent;
all data stays local (SQLite, WAL mode).
---
## Library API
Yaad is consumed as a Go library. The core entry points:
```go
import (
yaad "github.com/GrayCodeAI/yaad/engine"
"github.com/GrayCodeAI/yaad/storage"
)
// Open (or create) a memory store rooted at the repo / working dir.
store, err := storage.Open(".yaad")
eng := yaad.New(store)
// Store, recall, link, and inspect impact — the same operations the
// host agent exposes as tools (see the table above).
eng.Remember(ctx, yaad.Note{Type: "decision", Text: "Chose NATS for backpressure"})
hits, _ := eng.Recall(ctx, "why did we choose NATS?")
```
See [ARCHITECTURE.md](ARCHITECTURE.md) and [api/openapi.yaml](api/openapi.yaml) for the
full surface. Versioning/rollback, export/import, decay, and GC are all available as
engine methods (the host agent decides which to expose).
---
## Configuration
Generated at `.yaad/config.toml`:
```toml
[server]
port = 3456
host = "127.0.0.1"
[memory]
hot_token_budget = 800
warm_token_budget = 800
max_memories = 10000
[search]
bm25_weight = 0.5
vector_weight = 0.5
default_limit = 10
[decay]
enabled = true
half_life_days = 30
min_confidence = 0.1
boost_on_access = 0.2
[git]
watch = true
auto_stale = true
```
---
## Development
```bash
git clone https://github.com/GrayCodeAI/yaad.git
cd yaad
make build # go build ./... (library packages; no standalone binary)
make test # Run all tests
make cover # Coverage report (coverage.out + coverage.html)
make ci # Everything CI runs (tidy, fmt, vet, lint, test-race, security)
```
---
## Documentation
| Doc | What |
|---|---|
| [ARCHITECTURE.md](ARCHITECTURE.md) | Technical architecture |
| [COMPARISON.md](COMPARISON.md) | vs Mem0, Letta, Engram, agentmemory |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
| [CHANGELOG.md](CHANGELOG.md) | Release notes |
| [api/openapi.yaml](api/openapi.yaml) | OpenAPI spec |
---
## Community
- **Discord**: [GrayCodeAI](https://discord.gg/UqMbQJRE5)
- **Issues**: [GitHub Issues](https://github.com/GrayCodeAI/yaad/issues)
- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md)
---
<div align="center">
**MIT** © 2026 [GrayCodeAI](https://github.com/GrayCodeAI)
*yaad (याद) — Hindi/Urdu for memory, remembrance*
</div>
