Skip to content

Commit 8002f14

Browse files
Patel230Patel230
committed
feat: initial release v0.1.0
Yaad (याद) — model-agnostic, graph-native memory for coding agents. - Relaxed DAG (LPG) in SQLite via modernc.org/sqlite (pure Go, no CGO) - 9 coding-specific node types, 8 edge types with cycle enforcement - MCP server (12 tools), REST/HTTPS (25+ endpoints), gRPC (streaming) - Works with 10 agents: claude-code, cursor, gemini-cli, opencode, codex-cli, cline, windsurf, goose, roo-code, aider - Auto-capture hooks, session compression, proactive context - Hybrid search: BM25 + vector + graph with RRF fusion - Git chunk sync for team sharing (no merge conflicts) - TUI (Bubbletea), web dashboard (D3.js), benchmark harness - TypeScript OpenCode plugin, Claude Code bash plugin - Benchmark: R@5=100%, MRR=0.767, ~50ms latency Phases 1-5 complete. 14/14 tests passing. 6,747 lines Go.
0 parents  commit 8002f14

51 files changed

Lines changed: 8820 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Binary
2+
yaad
3+
yaad.exe
4+
5+
# Database (local, not shared)
6+
*.db
7+
*.db-shm
8+
*.db-wal
9+
10+
# Sync tracking (local state)
11+
.yaad/.imported
12+
13+
# Embeddings cache
14+
*.vec
15+
16+
# Build artifacts
17+
dist/
18+
*.test
19+
20+
# IDE
21+
.idea/
22+
.vscode/
23+
*.swp
24+
25+
# OS
26+
.DS_Store
27+
Thumbs.db

‎ARCHITECTURE.md‎

Lines changed: 418 additions & 0 deletions
Large diffs are not rendered by default.

‎CHANGELOG.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Changelog
2+
3+
All notable changes to Yaad are documented here.
4+
5+
## [0.1.0] — 2026-04-28
6+
7+
### Initial Release
8+
9+
**Core**
10+
- Relaxed DAG memory graph (Labeled Property Graph in SQLite)
11+
- 9 coding-specific node types: convention, decision, bug, spec, task, skill, preference, file, entity
12+
- 8 edge types with cycle enforcement: led_to, supersedes, caused_by, learned_in, part_of (acyclic) + relates_to, depends_on, touches (cyclic allowed)
13+
- Pure Go SQLite via `modernc.org/sqlite` — no CGO, no C compiler required
14+
- FTS5 full-text search with multi-word OR query support
15+
- SHA-256 content deduplication
16+
- Auto entity extraction (files, packages, functions, classes)
17+
- Privacy filtering (strips API keys, tokens, secrets on ingest)
18+
19+
**Interfaces**
20+
- MCP server (stdio, 12 tools) — works with any MCP-compatible agent
21+
- REST/HTTPS API (25+ endpoints, port 3456)
22+
- gRPC server (port 3457) with WatchMemories streaming
23+
- SSE streaming at `/yaad/events`
24+
- CLI (30 commands)
25+
- Web dashboard at `/yaad/ui` (D3.js force graph)
26+
27+
**Agent Integration**
28+
- `yaad setup` for 10 agents: claude-code, cursor, gemini-cli, opencode, codex-cli, cline, windsurf, goose, roo-code, aider
29+
- Auto-capture hooks: SessionStart, PostToolUse, SessionEnd
30+
- CLAUDE.md / .cursorrules / AGENTS.md bi-directional bridge
31+
32+
**Memory Intelligence**
33+
- Hot/warm/cold tier system with token budget management
34+
- Graph-aware memory decay (half-life, orphan/superseded 2× faster)
35+
- Git-aware staleness detection (propagates through graph)
36+
- Hybrid search: BM25 + vector + graph with RRF fusion
37+
- Contextual re-ranking: centrality × recency × confidence × tier
38+
- Proactive context prediction
39+
- Session compression → summary nodes
40+
- Memory feedback API (approve/edit/discard)
41+
- Version history + rollback
42+
43+
**Team & Scale**
44+
- Git chunk sync (`.yaad/chunks/*.jsonl.gz`) — append-only, no merge conflicts
45+
- Team memory namespacing
46+
- Skill/procedural memory with step sequences
47+
- JSON/Markdown/Obsidian export
48+
- Multi-project memory linking
49+
- LongMemEval-style benchmark harness
50+
51+
**Protocols**
52+
- HTTPS/TLS with auto self-signed cert generation
53+
- gRPC with protobuf service definition
54+
- WebSocket/SSE for real-time memory events

‎COMPARISON.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Yaad vs OSS — Competitive Comparison
2+
3+
## Feature Matrix
4+
5+
| Feature | **Yaad** | **Mem0** 54k⭐ | **Letta** 22k⭐ | **Cognee** 17k⭐ | **memU** 13k⭐ | **MemOS** 9k⭐ | **Engram** 3k⭐ | **agentmemory** 2k⭐ |
6+
|---|---|---|---|---|---|---|---|---|
7+
| Focus | Coding agents | General AI | General AI | General AI | Proactive agents | General AI | Coding agents | Coding agents |
8+
| Language | Go | Python | Python | Python | Python | Python/TS | Go | TypeScript |
9+
| Graph memory | ✅ Relaxed DAG | ⚠️ Optional Neo4j | ❌ Flat blocks | ✅ Knowledge graph | ❌ Hierarchical | ❌ Flat | ❌ Flat | ⚠️ Basic entity graph |
10+
| Coding-specific types | ✅ 9 types | ❌ Generic | ❌ Core/archival | ❌ Generic | ❌ Generic | ⚠️ Skills | ❌ Generic | ⚠️ 4 tiers |
11+
| Tiered loading | ✅ Hot/warm/cold | ❌ | ✅ 2-tier | ❌ | ❌ | ❌ | ❌ | ⚠️ Token budget |
12+
| Graph traversal | ✅ BFS + impact | ❌ | ❌ | ✅ Graph-RAG | ❌ | ❌ | ❌ | ❌ |
13+
| Git-aware staleness | ✅ Graph-propagated | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
14+
| Entity extraction | ✅ Auto regex | ✅ LLM | ❌ | ✅ LLM | ✅ LLM | ✅ LLM | ❌ | ❌ |
15+
| Deduplication | ✅ SHA-256 | ✅ LLM | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ SHA-256 |
16+
| Agent file bridge | ✅ CLAUDE.md sync | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ MEMORY.md |
17+
| MCP server | ✅ 12 tools | ✅ Plugin | ❌ Own API | ✅ | ✅ | ✅ | ✅ | ✅ 51 tools |
18+
| REST API | ✅ 15 endpoints | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ 107 endpoints |
19+
| HTTPS/TLS | ✅ Phase 2 | ✅ Cloud | ✅ Cloud | ✅ | ❌ | ✅ Cloud | ❌ | ❌ |
20+
| gRPC + streaming | ✅ Phase 2 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
21+
| CLI | ✅ 16 commands | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
22+
| Auto-capture hooks | ✅ Phase 4 | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ 12 hooks |
23+
| Search | ✅ BM25+graph+vector | ✅ Vector+entity+BM25 | ✅ Vector | ✅ Graph-RAG | ✅ RAG+LLM | ✅ Vector+graph | ✅ FTS5 | ✅ BM25+vector+graph |
24+
| Memory decay | ✅ Graph-aware | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ Ebbinghaus |
25+
| Contradiction detection | ✅ Supersedes chain | ✅ LLM | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
26+
| Version history | ✅ Full rollback | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ Git snapshots |
27+
| Impact analysis | ✅ Graph traversal | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
28+
| Privacy filtering | ✅ Regex strip | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
29+
| Multi-agent | ✅ WAL + isolation | ✅ API scoping | ✅ Within runtime | ❌ | ✅ | ✅ | ❌ | ✅ Leases |
30+
| Zero external deps | ✅ SQLite only | ❌ Qdrant/pgvector | ❌ Postgres+vector | ❌ Multiple DBs | ❌ PostgreSQL | ❌ Neo4j+Qdrant+Redis | ✅ SQLite only | ❌ iii-engine |
31+
| Proactive memory | ⚠️ Phase 3 | ❌ | ❌ | ❌ | ✅ Core | ❌ | ❌ | ❌ |
32+
| Multi-modal | ⚠️ Phase 5 | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ |
33+
| Benchmarks | ⚠️ Phase 5 | ✅ LoCoMo | ❌ | ❌ | ✅ 92% | ✅ 75.8% | ❌ | ✅ 95.2% |
34+
35+
## Yaad's Unique Advantages
36+
37+
These features exist in **no other** lightweight coding memory system:
38+
39+
1. **Relaxed DAG in SQLite** — Graph power without Neo4j. Causal edges are acyclic, relational edges allow cycles.
40+
2. **Graph-propagated staleness** — File changes flag entire subgraphs, not just individual memories.
41+
3. **Impact analysis** — "What memories break if I change auth.ts?" via reverse graph traversal.
42+
4. **9 coding-specific node types** — First-class `convention`, `decision`, `bug`, `spec`, `task`, `preference`, `session`, `file`, `entity`.
43+
5. **3-stage graph search** — Seed nodes (BM25) → graph expansion (BFS) → subgraph ranking (centrality + recency).
44+
6. **Graph-aware decay** — Orphan nodes decay faster, connected nodes boost each other on access.
45+
7. **Bi-directional agent file bridge** — Sync with CLAUDE.md, .cursorrules, AGENTS.md.
46+
8. **Full version history + rollback** — Undo bad memory updates with `yaad rollback`.
47+
9. **gRPC + streaming** — Only coding memory system with gRPC. Auto-generated SDKs, real-time memory events, ~10x faster than REST.
48+
49+
## Where Yaad Is Behind (Honest)
50+
51+
| Gap | Who's Ahead | Yaad's Timeline |
52+
|---|---|---|
53+
| Proactive intent prediction | memU | Phase 3 |
54+
| Multi-modal (images) | MemOS, memU | Phase 5 |
55+
| Skill/procedural memory | MemOS, memU | Phase 5 |
56+
| LLM-based entity extraction | Mem0, Cognee | Phase 3 (regex in Phase 1) |
57+
| Auto-capture hooks | agentmemory (12 hooks) | Phase 4 |
58+
| Benchmark scores | agentmemory 95.2%, MemOS 75.8% | Phase 5 |
59+
| Community/ecosystem | Mem0 (54k⭐) | Day 0 — need to ship |
60+
61+
## Positioning
62+
63+
```
64+
Coding-Specific
65+
▲
66+
│
67+
│ ● Yaad
68+
Engram ● │ (graph + tiers + git-aware + zero deps)
69+
agentmemory ● │
70+
│
71+
Lightweight ───────────┼──────────── Feature-Rich
72+
│
73+
Mem0 ● │ ● Letta
74+
memvid ● │ ● MemOS
75+
memU ● │ ● Cognee
76+
│
77+
▼
78+
General-Purpose
79+
```
80+
81+
**Yaad's bet**: Coding agents don't need a heavy general-purpose memory system. They need a lightweight, graph-native, coding-specific memory that understands codebases, tracks relationships between decisions, and detects when things go stale. All in a single binary with zero dependencies.

‎LICENSE‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
Apache License
2+
Version 2.0, January 2004
3+
http://www.apache.org/licenses/
4+
5+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6+
7+
1. Definitions.
8+
9+
"License" shall mean the terms and conditions for use, reproduction,
10+
and distribution as defined by Sections 1 through 9 of this document.
11+
12+
"Licensor" shall mean the copyright owner or entity authorized by
13+
the copyright owner that is granting the License.
14+
15+
"Legal Entity" shall mean the union of the acting entity and all
16+
other entities that control, are controlled by, or are under common
17+
control with that entity.
18+
19+
"You" (or "Your") shall mean an individual or Legal Entity
20+
exercising permissions granted by this License.
21+
22+
"Source" form shall mean the preferred form for making modifications,
23+
including but not limited to software source code, documentation
24+
source, and configuration files.
25+
26+
"Object" form shall mean any form resulting from mechanical
27+
transformation or translation of a Source form, including but
28+
not limited to compiled object code, generated documentation,
29+
and conversions to other media types.
30+
31+
"Work" shall mean the work of authorship made available under
32+
the License, as indicated by a copyright notice that is included in
33+
or attached to the work.
34+
35+
"Derivative Works" shall mean any work, whether in Source or Object
36+
form, that is based on (or derived from) the Work and for which the
37+
editorial revisions, annotations, elaborations, or other modifications
38+
represent, as a whole, an original work of authorship.
39+
40+
"Contribution" shall mean, as submitted to the Licensor for inclusion
41+
in the Work by the copyright owner or by an individual or Legal Entity
42+
authorized to submit on behalf of the copyright owner.
43+
44+
"Contributor" shall mean Licensor and any Legal Entity on behalf of
45+
whom a Contribution has been received by the Licensor and included
46+
within the Work.
47+
48+
2. Grant of Copyright License. Subject to the terms and conditions of
49+
this License, each Contributor hereby grants to You a perpetual,
50+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
51+
copyright license to reproduce, prepare Derivative Works of,
52+
publicly display, publicly perform, sublicense, and distribute the
53+
Work and such Derivative Works in Source or Object form.
54+
55+
3. Grant of Patent License. Subject to the terms and conditions of
56+
this License, each Contributor hereby grants to You a perpetual,
57+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
58+
patent license to make, use, sell, offer for sale, import, and
59+
otherwise transfer the Work.
60+
61+
4. Redistribution. You may reproduce and distribute copies of the
62+
Work or Derivative Works thereof in any medium, with or without
63+
modifications, and in Source or Object form, provided that You
64+
meet the following conditions:
65+
66+
(a) You must give any other recipients of the Work or Derivative
67+
Works a copy of this License; and
68+
69+
(b) You must cause any modified files to carry prominent notices
70+
stating that You changed the files; and
71+
72+
(c) You must retain, in the Source form of any Derivative Works
73+
that You distribute, all copyright, patent, trademark, and
74+
attribution notices from the Source form of the Work; and
75+
76+
(d) If the Work includes a "NOTICE" text file, you must include a
77+
readable copy of the attribution notices contained within such
78+
NOTICE file.
79+
80+
5. Submission of Contributions. Unless You explicitly state otherwise,
81+
any Contribution submitted for inclusion in the Work shall be under
82+
the terms and conditions of this License.
83+
84+
6. Trademarks. This License does not grant permission to use the trade
85+
names, trademarks, service marks, or product names of the Licensor.
86+
87+
7. Disclaimer of Warranty. Unless required by applicable law or
88+
agreed to in writing, Licensor provides the Work on an "AS IS"
89+
BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
90+
91+
8. Limitation of Liability. In no event and under no legal theory
92+
shall any Contributor be liable for any damages arising from this
93+
Work, even if such Contributor has been advised of the possibility
94+
of such damage.
95+
96+
9. Accepting Warranty or Additional Liability. While redistributing
97+
the Work, You may offer acceptance of support, warranty, indemnity,
98+
or other liability obligations consistent with this License.
99+
100+
END OF TERMS AND CONDITIONS
101+
102+
Copyright 2026 Yaad Contributors
103+
104+
Licensed under the Apache License, Version 2.0 (the "License");
105+
you may not use this file except in compliance with the License.
106+
You may obtain a copy of the License at
107+
108+
http://www.apache.org/licenses/LICENSE-2.0
109+
110+
Unless required by applicable law or agreed to in writing, software
111+
distributed under the License is distributed on an "AS IS" BASIS,
112+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
113+
See the License for the specific language governing permissions and
114+
limitations under the License.

‎Makefile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
BINARY := yaad
2+
PKG := ./cmd/yaad
3+
4+
.PHONY: build run test clean install
5+
6+
build:
7+
go build -o $(BINARY) $(PKG)
8+
9+
run: build
10+
./$(BINARY)
11+
12+
test:
13+
go test ./...
14+
15+
clean:
16+
rm -f $(BINARY)
17+
18+
install:
19+
go install $(PKG)

0 commit comments

Comments
 (0)