GrayCodeAI · Patel230 · Jun 8, 2026 · Jun 8, 2026 · Jun 9, 2026 · Jun 9, 2026
diff --git a/.DS_Store b/.DS_Store
diff --git a/.dockerignore b/.dockerignore
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1,26 @@
+# CODEOWNERS for yaad (memory & knowledge-graph engine)
+* @GrayCodeAI/maintainers
+
+# Engine core
+/engine/         @GrayCodeAI/core-team
+/embeddings/     @GrayCodeAI/core-team
+/graph/          @GrayCodeAI/core-team
+/compact/        @GrayCodeAI/core-team
+/dedup/          @GrayCodeAI/core-team
+/conflict/       @GrayCodeAI/core-team
+/browse/         @GrayCodeAI/core-team
+/config/         @GrayCodeAI/core-team
+/hooks/          @GrayCodeAI/core-team
+
+# API surface
+/api/            @GrayCodeAI/core-team
+
+# CI / release / build tooling
+/.github/        @GrayCodeAI/devops-team
+/Makefile        @GrayCodeAI/devops-team
+/lefthook.yml    @GrayCodeAI/devops-team
+/scripts/        @GrayCodeAI/devops-team
+
+# Documentation
+*.md             @GrayCodeAI/docs-team
+/docs/           @GrayCodeAI/docs-team
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -32,7 +32,7 @@ body:
         - "CLI (`yaad ...`)"
         - "MCP (stdio / hawk integration)"
         - "REST (`/yaad/...` HTTP)"
-        - "Go SDK (`internal` packages or `cmd/yaad`)"
+        - "Go SDK (library API / `internal` packages)"
         - "Python SDK (`sdk/python`)"
         - "TypeScript SDK (`sdk/typescript`)"
         - "Embedded library use"

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,5 +1,5 @@
 # Canonical CI workflow for hawk-eco Go repos.
-# Source of truth: .shared-templates/workflows/go-ci.yml.tmpl
+# Source of truth: https://github.com/GrayCodeAI/hawk/blob/main/.shared-templates/workflows/go-ci.yml.tmpl
 #
 # Two deployment models:
 #
@@ -32,7 +32,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  GO_VERSION: "1.26.4"
+  GO_VERSION: "1.26.5"
   GOPRIVATE: "github.com/GrayCodeAI/*"
   GONOSUMDB: "github.com/GrayCodeAI/*"
   GONOSUMCHECK: "1"
@@ -52,9 +52,11 @@ jobs:
           cache: true
       - name: Clone tok (workspace dep)
         run: git clone --depth=1 https://github.com/GrayCodeAI/tok.git ../tok
+      - name: Boundary guard
+        run: bash ./scripts/check-ecosystem-boundaries.sh
       - name: gofumpt diff
         run: |
-          go install mvdan.cc/gofumpt@v0.7.0
+          go install mvdan.cc/gofumpt@v0.10.0
           out=$(gofumpt -l .)
           if [ -n "$out" ]; then
             echo "::error::gofumpt would reformat the following files:"
@@ -78,6 +80,8 @@ jobs:
           cache: true
       - name: Clone tok (workspace dep)
         run: git clone --depth=1 https://github.com/GrayCodeAI/tok.git ../tok
+      - name: Boundary guard
+        run: bash ./scripts/check-ecosystem-boundaries.sh
       - uses: golangci/golangci-lint-action@4afd733a84b1f43292c63897423277bb7f4313a9 # v7.0.0
         with:
           version: v2.1.0
@@ -99,6 +103,8 @@ jobs:
           cache: true
       - name: Clone tok (workspace dep)
         run: git clone --depth=1 https://github.com/GrayCodeAI/tok.git ../tok
+      - name: Boundary guard
+        run: bash ./scripts/check-ecosystem-boundaries.sh
       - name: Tidy check
         run: |
           go mod tidy
@@ -114,7 +120,7 @@ jobs:
       - name: Coverage threshold
         run: |
           COVERAGE=$(go tool cover -func=coverage.out | tail -1 | grep -oE '[0-9]+\.[0-9]+' || echo "0")
-          THRESHOLD=52
+          THRESHOLD=49
           if [ "$(echo "$COVERAGE < $THRESHOLD" | bc -l)" -eq 1 ]; then
             echo "::error::Coverage ${COVERAGE}% is below threshold ${THRESHOLD}%"
             exit 1
@@ -166,7 +172,7 @@ jobs:
         run: git clone --depth=1 https://github.com/GrayCodeAI/tok.git ../tok
       - name: deadcode
         run: |
-          go install golang.org/x/tools/cmd/deadcode@latest
+          go install golang.org/x/tools/cmd/deadcode@v0.30.0
           deadcode ./... 2>&1 | head -50
 
   # -------------------------------------------------------------------------
@@ -201,9 +207,9 @@ jobs:
         run: git clone --depth=1 https://github.com/GrayCodeAI/tok.git ../tok
       - name: Run fuzz targets
         run: |
-          go test -fuzz=FuzzContentHash     -fuzztime=60s ./engine/... || true
-          go test -fuzz=FuzzExtractEntities -fuzztime=60s ./engine/... || true
-          go test -fuzz=FuzzRecallOpts      -fuzztime=60s ./engine/... || true
+          go test -fuzz=FuzzContentHash     -fuzztime=60s ./engine
+          go test -fuzz=FuzzExtractEntities -fuzztime=60s ./engine
+          go test -fuzz=FuzzRecallOpts      -fuzztime=60s ./engine
 
   # -------------------------------------------------------------------------
   # Cross-platform build matrix — only for repos that produce a binary.

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,31 @@
+# Release workflow for yaad (Go library — no binaries).
+# Triggered when a v* tag is pushed; publishes a GitHub Release with
+# auto-generated notes. Consumers depend on the tag via
+# `go get github.com/GrayCodeAI/yaad@vX.Y.Z`.
+
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # v2.2.2
+        with:
+          generate_release_notes: true
+          draft: false
+          prerelease: auto
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml
@@ -37,6 +37,6 @@ jobs:
           retention-days: 5
 
       - name: Upload to code-scanning
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4
         with:
           sarif_file: scorecard-results.sarif
diff --git a/.gitignore b/.gitignore
@@ -6,15 +6,32 @@
 bin/
 dist/
 
-# Database / local cache
+# Database / local cache (SQLite main DB + WAL/SHM sidecars)
 elrond*.db
 *.codegraph.db
+*.db-wal
+*.db-shm
+.codegraph/*.db
 
-# Local yaad runtime state (key material + SQLite database — never commit)
+# Local yaad runtime state (key material + SQLite database + local config — never commit)
+.yaad/
 .yaad/integrity.key
 .yaad/yaad.db
+.yaad/config.toml
+
+# Python SDK build artifacts
+__pycache__/
+*.pyc
 
 # Dev tool state
 .claude/
 .codegraph/
 coverage.out
+
+# Go workspace (local dev only — each developer creates their own)
+go.work
+go.work.sum
+
+# macOS
+.DS_Store
+.gocache/
diff --git a/.yaad/config.toml b/.yaad/config.toml
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,125 +1,43 @@
-# AGENTS.md — Yaad (याद)
+---
+description: yaad — persistent memory engine build and test conventions.
+globs: "*.go,*.toml,*.yaml"
+alwaysApply: false
+---
 
-Graph-based persistent memory for coding agents. One config line. Works with any MCP agent. Zero setup.
+# yaad Conventions
 
-## Design Principles
-
-- **Zero setup** — single config line to enable persistent memory
-- **MCP compatible** — works with any MCP-capable agent
-- **Graph-based** — knowledge stored as a graph, not flat key-value
-- **Self-healing** — memory consolidates and prunes automatically
-
-## Observability
-
-See [hawk/docs/OTEL-CONVENTIONS.md](https://github.com/GrayCodeAI/hawk/blob/main/docs/OTEL-CONVENTIONS.md) for the shared OpenTelemetry attribute vocabulary (`gen_ai.*`, `cost.usd`, etc.) used across all GrayCodeAI repos.
+Graph-based persistent memory engine for coding agents.
 
 ## Build & Test
 
 ```bash
-go test ./...                    # Run all tests
-go test -race ./...              # Race detector
-go test -coverprofile=c.out ./... # Coverage
-go vet ./...                     # Static analysis
-gofumpt -w .                     # Format
+make build         # go build ./...
+make test          # Run tests
+make cover         # Coverage report
+make ci            # Full CI suite
 ```
 
-## Architecture
-
-- `memory.go` — Core memory graph (nodes, edges, queries)
-- `server.go` — MCP server implementation
-- `consolidator.go` — Automatic memory consolidation
-- `recall.go` — Fused recall with atomic operations
-- `rest.go` — REST API for non-MCP clients
-- `internal/` — Storage, indexing, search internals
-
-## Conventions
-
-- Go 1.26+, pure Go, no CGO
-- Table-driven tests
-- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
-- No `Co-authored-by:` trailers (auto-stripped by githook)
-- `gofumpt` formatting enforced in CI
-- SQLITE_BUSY prevention: use `settleSelfLink` waits in tests
-
-## Common Pitfalls
-
-- FusedRecall uses atomic loads for `NodesStored` — don't use regular reads
-- SelfLink settling needs adequate wait time in tests (prevents SQLITE_BUSY)
-- MCP prompts are defined in `internal/server/mcp_prompts.go`
+Optional demo TUI (nested module — **not** part of the core library graph):
 
-## Naming Conventions
-
-- **Engine is the core facade**: `engine.Engine` with methods `Remember()`, `Recall()`, `Context()`, `Feedback()`, `Forget()`, `Compact()`
-- **Storage layer uses Store interface**: `storage.Store` with `GetNode()`, `UpdateNode()`, `ListSessions()`, `GetEdgesFrom()`, etc.
-- **Graph layer**: `graph.New(store, git)` — wraps store with graph operations, community detection, drift search
-- **Node types are lowercase strings**: `"convention"`, `"decision"`, `"task"`, `"bug"`, `"preference"`, `"spec"` — validated on input
-- **Scopes are lowercase strings**: `"project"`, `"global"` — used for memory isolation
-- **Hooks package**: `hooks.New(engine, dir)` returns a `Runner` with `SessionStart()`, `PostToolUse()`, `SessionEnd()`
-- **Config uses TOML**: `config.Load(dir)` reads `.yaad/config.toml` — struct fields map to `[section] key` format
-- **Error sentinels**: defined in `engine/errors.go` — `Err` prefix pattern
-- **Skill types**: `skill.Skill` with `Name`, `Description`, `Steps` — stored as memory nodes, loaded by name
-
-## API Patterns
-
-- **Engine.Remember()**: takes `RememberInput` struct (Type, Content, Scope, Key, Project, Session, Agent, Pinned) — returns `(Node, error)`
-- **Engine.Recall()**: takes `RecallOpts` struct (Query, Limit, Budget, Project) — returns result with Nodes slice
-- **Engine.Context()**: takes project string — returns tiered context (hot/warm/cold) formatted as markdown
-- **Engine.Feedback()**: takes node ID + action (`FeedbackApprove`, `FeedbackEdit`, `FeedbackDiscard`) — modifies confidence
-- **Keyed upsert**: `Remember()` with `Key` field updates existing node instead of creating duplicate — same ID, incremented Version
-- **Token budget enforcement**: `RecallOpts.Budget` limits total returned tokens — stops adding nodes when budget exceeded
-- **Auto-decay on session start**: `hooks.SessionStart()` triggers `RunDecay()` — confidence decreases based on `HalfLifeDays`
-- **Self-linking**: after storing a node, the engine finds related nodes via FTS and creates edges — best-effort, async
-- **Entity extraction**: `Remember()` auto-extracts file paths, package names, function names — creates anchor nodes + `touches` edges
-
-## Testing Patterns
+```bash
+cd cmd/yaad-tui && go test ./... && go build -o yaad-tui .
+```
 
-- **Integration test package**: `package integration_test` in `yaad_test.go` — tests the full engine lifecycle
-- **`setup(t)` helper**: returns `(engine, cleanup func)` — creates in-memory SQLite store, wires engine, returns cleanup
-- **`ctx()` helper**: returns `context.Background()` — used throughout for brevity
-- **Lifecycle tests**: `TestHawkFullSessionLifecycle` — session start, tool uses, session end, recall verification
-- **Table-driven relevance tests**: `TestRelevanceFilterScoring` — struct slice with `tool, input, output, err, shouldCapture` fields
-- **Concurrent safety test**: `TestConcurrentHawkOperations` — 3 goroutines doing remember/recall/context simultaneously
-- **Edge case tests**: max content length (10000 chars), invalid node type, empty content — all should return errors
-- **Config tests**: `TestConfigLoadDefaults`, `TestConfigLoadFromFile` — verify TOML parsing and default values
-- **Compaction test**: create low-confidence nodes, run `Compact()`, verify merge count
-- **Rollback test**: remember, edit, rollback to version 1 — verify content restored
+## Architecture
 
-## Refactoring Guidelines
+```
+engine/             # Memory engine (graph, search, ingest)
+storage/            # SQLite (WAL mode) + FTS5
+cmd/yaad-tui/       # Optional Bubble Tea demo (own go.mod; no core TUI deps)
+internal/
+  search/           # search helpers
+  ...
+```
 
-- **Safe to refactor**: `engine/decay.go`, `engine/scoring.go`, `engine/rerank.go` — internal ranking logic
-- **Safe to refactor**: `engine/query.go`, `engine/query_expand.go`, `engine/query_planner.go` — search internals
-- **Safe to refactor**: `hooks/` package — relevance scoring, tool filtering — no external API contract
-- **Do not touch**: `engine.Remember()`, `Recall()`, `Context()`, `Feedback()` signatures — core API contract
-- **Do not touch**: `storage.Store` interface — implemented by SQLite, used by engine, graph, hooks
-- **Do not touch**: `graph.Graph` interface — used by engine and hooks for relationship queries
-- **Do not touch**: Node type strings (`"convention"`, `"decision"`, etc.) — used in MCP prompts and client code
-- **Safe to extend**: add new node types, new edge types, new search strategies, new consolidation passes
-- **When adding MCP tools**: add to `internal/server/` — each tool is a separate handler function
+## Ecosystem Boundaries
 
-## Key File Locations
+- Uses local-only types; do not import `hawk/internal/*` or legacy paths
+- Do not import other engines (`eyrie`, `tok`, `trace`, `sight`, `inspect`)
+- Embedded by host agents (hawk); ships no standalone `yaad` binary
 
-| What | Where |
-|---|---|
-| Engine core | `engine/engine_core.go` (facade with Remember, Recall, Context, Feedback, etc.) |
-| Engine interface | `engine/interface.go` (if exists — defines Engine contract) |
-| Remember implementation | `engine/remember.go` |
-| Recall implementation | `engine/recall.go` |
-| Fused recall (BM25 + vector + graph + temporal) | `engine/fused_recall.go` |
-| Context generation | `engine/context.go`, `engine/context_pack.go` |
-| Decay logic | `engine/decay.go` |
-| Feedback handling | `engine/feedback.go` |
-| Compaction | `engine/session_compress.go`, `engine/topic_consolidation.go` |
-| Self-linking | `engine/selflink.go` |
-| Entity extraction | `engine/entities.go`, `engine/entity_boost.go` |
-| Proactive context | `engine/proactive.go` |
-| Mental model | `engine/mental/` |
-| Storage interface | `storage/interface.go` |
-| SQLite storage | `storage/sqlite.go` |
-| Graph operations | `graph/graph.go`, `graph/community.go`, `graph/drift_search.go` |
-| Hooks (session lifecycle) | `hooks/` (SessionStart, PostToolUse, SessionEnd, ShouldCapture) |
-| Skills | `skill/` (Store, Load, Replay) |
-| Config loading | `config/` (TOML parsing, defaults) |
-| MCP server | `internal/server/` |
-| MCP prompts | `internal/server/mcp_prompts.go` |
-| Integration tests | `yaad_test.go` (full lifecycle, concurrent, edge cases) |
-| Linter config | `.golangci.yml` (errcheck, govet, staticcheck, gocritic, bodyclose, noctx) |
+For full hawk-eco extension guidelines, see [hawk/AGENTS.md](https://github.com/GrayCodeAI/hawk/blob/main/AGENTS.md).