Repository navigation
feat!: retire the knowledge-graph surface (triples, entities, episode links) - #35
Merged
Merged
Conversation
… links) BREAKING CHANGE: removes the add_knowledge and link_episodes MCP tools and the knowledge/entities/episode_links tables. A startup drop-migration removes the tables from existing databases. The knowledge-graph layer never earned its place. Controlled retrieval evaluations showed that on a real corpus, good hybrid search over the episodes retrieves better than the derived triples — the episodes are the source of truth and are kept in full. The derived graph was a lossier third representation of what the episodes and search already cover. Meanwhile the two MCP tools cost prompt tokens on every request and offered models a meaningless option. Removing the surface makes the tool set leaner and the product's intent clearer. Why a full teardown rather than hiding the tools: a live-but-dead schema is a contract with every user's database (dead tables created forever, reembed counting empty tables, orphaned rows for anyone who used add_knowledge). One clean break beats an indefinite dead-schema tax plus a second migration later that lands on users. - MCP: remove add_knowledge, link_episodes (+ handlers). Keep add_memory, search, get_episodes, update_episode, get_status. - DB: remove entities/knowledge/episode_links schema + all Entity/Knowledge/ EpisodeLink store methods; add a defensive, idempotent drop-migration that logs the row counts it removes before dropping and never bricks startup. - Reembed: episodes only (StaleEmbeddingCounts, CountReembedTargets, runReembed). - Models: remove Entity, KnowledgeTriple, EpisodeLink. - Tests: remove knowledge-graph tests; add drop-migration coverage. Validated against a populated database (924 episodes / 2340 triples / 1292 entities / 1988 links): migration logs the counts, drops all three tables, preserves every episode with embeddings intact, and is idempotent on rerun. A database with no knowledge rows sees a clean no-op drop. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mikejgray
force-pushed
the
chore/remove-knowledge-graph
branch
from
July 8, 2026 04:25
4e3392d to
918ae7d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Removes the knowledge-graph layer from Engram entirely:
add_knowledge,link_episodes(+ their handlers). Surviving tools:add_memory,search,get_episodes,update_episode,get_status.knowledge,entities,episode_linkstables + indexes. A startup drop-migration removes them from existing DBs.Entity,KnowledgeTriple,EpisodeLinkdeleted.BREAKING CHANGE — major version bump. Removes shipped MCP tools and drops tables.
Why
The knowledge-graph layer never earned its place. Controlled retrieval evaluations showed that on a real corpus, good hybrid search over the episodes retrieves better than the derived triples — the episodes are the source of truth and are kept in full. The derived graph was a lossier third representation of information the episodes + search already cover.
Meanwhile the two MCP tools cost prompt tokens on every request and offered models a meaningless option (an attractive nuisance: a model reasonably calls
add_knowledge, fragmenting facts off from the episodes that are the actual value).Why a full teardown rather than hiding the tools: a live-but-dead schema is a contract with every user's database — dead tables created forever, reembed counting empty tables, and orphaned rows for anyone who used
add_knowledge. One clean break beats an indefinite dead-schema tax plus a second migration later that lands on users.Drop-migration
Defensive and idempotent: counts rows per table (guarded so absent tables read 0 silently), logs what it removes to stderr before dropping, drops in FK-safe order (links → knowledge → entities), and logs-but-never-errors on failure so it cannot brick startup. The existing post-migration
CHECKPOINTflushes the drops, closing the WAL-replay window.Validation
Tested against a populated database (924 episodes / 2340 triples / 1292 entities / 1988 links):
A database with no knowledge rows sees a clean no-op drop.
go build,go vet,go test ./...,gofmt -lall clean. Net diff: +66 / −1197 across 8 files.Migration note for users
If you relied on
add_knowledge/link_episodes, export any triples you care about before upgrading — the tables are dropped on first start of this version. Episodes are never touched.🤖 Generated with Claude Code