memkith 0.1.0b1

Multiplayer context for AI coding agents

Memkith

Multiplayer context for AI coding agents.

AI coding tools make one developer faster. Memkith makes the whole software team legible to those tools by serving the agent the episodes behind the code: architecture decisions, requirements debates, review outcomes, failed attempts, post-mortems, governance rules, and onboarding knowledge.

Those episodes are scoped to the code they affect and gated by git visibility. Draft context stays local while the code is local; published context becomes available when the relevant code is shared, with provenance the agent can cite.

Memkith is being built so an agent can answer questions like:

• What decision led to this shape?
• What did the team already try here?
• Which review or compliance constraints govern this change?
• What branch-local context should affect this file?

Product Thesis

Software development is multiplayer, but today's AI coding tools mostly accelerate individuals. They can inspect code and write diffs, but they do not inherit the coordination history around that code: decisions, debates, rollback notes, compliance constraints, review intent, and team-specific rules.

Memkith exists to make that coordination history executable by agents.

• Problem: agents write code without the team context that human collaborators use to avoid repeated mistakes, review churn, and policy violations.
• Insight: the useful unit is an episode tied to code scope and visibility, not generic chat memory.
• Product: a git-aware context layer that captures episodes, publishes them with code visibility, and retrieves them before an agent plans or edits.
• Wedge: multiplayer AI for software teams, starting with scoped engineering memory for coding agents.

Why It Exists

The bottleneck in software is not only typing code. It is coordinating across roles and time. Requirements, architecture calls, PR debates, compliance notes, incident learnings, and onboarding explanations shape every good diff, but they are scattered across tools and rarely reach the next AI session at the moment they matter.

Today that knowledge is fragmented across AGENTS.md, CLAUDE.md, Cursor rules, README notes, PR reviews, issue threads, and tribal knowledge. Memkith turns that scattered context into a shared, reviewable layer that any MCP-compatible coding agent can read from and write to.

What Memkith is

• Multiplayer context: team episodes are available to every authorized agent working in the repo
• Cross-agent: one layer shared across Claude Code, Cursor, Copilot, and other MCP-compatible tools
• Git-aware: context is intended to follow code visibility first and code lineage second
• Graph-first: all knowledge is stored as a typed graph — topics, memories, scopes, and the edges between them
• LLM-mediated: developers ask questions about code, and the LLM retrieves relevant episodes to answer them
• Reviewable: memory creation follows the agent's existing permission model
• Durable: memories are immutable objects connected by contradiction, reinforcement, and supersession edges

Quick start

Five minutes from clone to first recall. Requires Python 3.11+ and uv.

# Install (not yet on PyPI — install from git)
uv tool install --from git+https://github.com/sakshambedi/thread.ai memkith

# In any repo you want memkith to remember
cd your-repo
memkith init                       # writes .memkith/config.json, derives repo_id
memkith login                      # browser OAuth against memkith.com
memkith status                     # confirm token + repo_id

Wire memkith into Claude Code so the agent can read and write memories. Add to ~/.claude.json (global) or .mcp.json (per-project):

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

Restart Claude Code, then bootstrap your existing rule files into memkith:

# Archives the original to .memkith/imported/<name>.<ts>.bak and replaces
# it with a memkith MCP pointer + live rules digest. Pass --no-replace-source
# to keep the original file in place.
memkith import CLAUDE.md
memkith import AGENTS.md           # if present

The agent should now see your governance rules at session start (memkith_rules) and recall them via memkith_recall when editing scoped files. Verify from the shell with memkith rules or memkith recall --files <path>.

Proof Of Concept

The proof of concept is intentionally narrower than the full vision.

• Draft memory stays local until the relevant code is pushed or otherwise made visible to collaborators.
• Published memory is anchored to concrete repo history so recall can be conservative and explainable.
• The system should record enough provenance now to support future handling of rebases, cherry-picks, and squash merges without forcing those cases into V1.

The near-term goal is to prove one thing well: agents should not retrieve engineering memory for code that does not exist in the collaborator's visible codebase.

Memory Model

Memkith stores engineering memory as a graph, but the graph is not meant to be a rigid tree.

The simplest way to view it is:

Topic (optional organizing label)
  └── Memory (a claim, decision, failure, rule, or insight)
        └── Scope (where it applies: file, directory, module, layer)

That is a useful mental model for humans and for the visualizer, but it is not the full canonical model.

The canonical model needs a few first-class dimensions:

• memory: the semantic thing learned
• scope: where that memory applies in the codebase
• provenance: where the memory came from
• visibility: whether it is local, published, merged, or archived
• anchor: which published revision or code state justifies recalling it
• relations: whether it reinforces, contradicts, supersedes, or relates to other memories

Topics still matter, but they should behave more like organizing labels or graph projections than the root of the data model.

A more faithful conceptual shape looks like this:

Observation / Episode
  └── creates or reinforces → Memory
Memory
  ├── touches → Scope
  ├── about → Topic
  ├── anchored_to → Revision
  ├── visible_via → Publish state
  └── relates_to / contradicts / supersedes → other memories

This matters because Memkith is trying to solve a trust problem, not just a retrieval problem. To decide whether a memory should be shown, the system eventually needs to know not only what the memory is about, but also why it is valid for the caller's current view of the repo.

Branches still act as visibility filters in the current proof of concept. Longer term, the retrieval model should become increasingly aware of published revision reachability rather than relying on branch structure alone.

Memory types

Type	Purpose	Example
rationale	Why a change was made	"PKCE chosen because app is public SPA client"
failure_record	What failed and should not be repeated	"Migration 042 failed, caused 30min downtime"
governance_rule	Standards and rules that govern changes	"All auth tokens must use short-lived JWTs"
prior_art	What was tried before	"Tried session cookies, failed on mobile"
success_condition	What worked and under which constraints	"Deploy requires green CI + staging smoke test"
impact_map	What code and workflows are affected	"Auth changes affect Payments, Login, Session"

Edge types

Edge	Between	Meaning
about	memory → topic	Memory belongs to topic
touches	memory → scope	Memory applies to this file/module/layer
contradicts	memory → memory	Conflicting assertions
supersedes	memory → memory	Source replaces target
reinforces	memory → memory	Source confirms target
relates_to	memory → memory	Topical connection
cross_references	topic → topic	Co-occurring topics
visible_on	memory → branch	Branch visibility (used as filter)
parent_of	branch → branch	Branch ancestry (used as filter)

MCP tools

Memkith keeps the agent surface intentionally small: three reads and one write.

Tool	Role	Description
memkith_rules	Read, pushed	Pushes governance rules for the current scope at session start
memkith_recall	Read, pulled	Retrieves relevant memories by file/module/layer scope using graph traversal
memkith_directives	Read, pushed	Returns always-on agent-behavior rules (not branch- or commit-aware)
memkith_learn	Write	Records new knowledge with automatic dedup, topic resolution, and scope wiring

CLI commands

memkith init                    # Bootstrap Memkith in current repo
memkith login                   # Authenticate with Memkith cloud
memkith learn <description>     # Record a memory
memkith recall --files <path>   # Query memories by file scope
memkith recall --scopes <kind:value,...>   # Query memories by broader scope
memkith rules                   # Show governance rules for current branch
memkith directive add <text>    # Add a standing agent-behavior rule (--user | --repo)
memkith directive list          # Show active directives for current scope
memkith directive remove <id>   # Revoke a directive
memkith directive hook          # Print PreToolUse injection payload (wire into .claude/settings.json)
memkith mcp                     # Run MCP server over stdio
memkith export-graph            # Export knowledge graph as JSON

Recall with scope context

Recall starts from the code scope, not a topic label:

# File scopes
memkith recall --files auth/service.py

# Broader scopes
memkith recall --scopes module:internal/auth,layer:domain

Learn with scope context

Memories can be grounded to specific parts of the codebase:

# File scopes (shorthand)
memkith learn --topic Auth --files auth/service.go,auth/handler.go "Use OIDC for all auth"

# General scope hints
memkith learn --topic Auth --scopes layer:domain,module:internal/core "Use OIDC for all auth"

Scope kinds: file, directory, module, layer.

Directives — standing agent-behavior rules

Directives are always-on rules that steer the agent before it plans or edits — distinct from code-scoped governance memories, which are branch- and commit-anchored. Use directives for things like "no bloat, keep code iterable" or "always run uv run not python -m". They apply to every action, everywhere.

memkith directive add "no bloat code, keep it iterable"    # --user (default) — portable across repos
memkith directive add "use conventional commits" --repo    # team-wide for this repo
memkith directive list                                     # merged user + repo view
memkith directive remove dir_abc123

Directives live in a dedicated Supabase table, not on the knowledge graph. Writes go through the bearer-gated server; reads fall back to .memkith/directives.cache.json when the server is unreachable so agent actions never block on network.

Wiring into Claude Code — add a PreToolUse hook so directives are injected before every edit/write/plan-exit:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|ExitPlanMode",
        "hooks": [{"type": "command", "command": "memkith directive hook"}]
      }
    ]
  }
}

Export and visualization

Export the knowledge graph and visualize it interactively:

# Export to file
memkith export-graph --out graph.json

# Load in the graph visualizer
cd graph_vizualizer && npm run dev
# Open http://localhost:3000 and click "Load Graph JSON"

The graph visualizer is a Next.js web app that renders the memory graph as an interactive force-directed view, with topic, memory, and scope structure visible alongside branch filtering, node inspection, and distance controls.

Local development

Requirements: Python 3.11+, uv, Node.js 18+ (for graph visualizer)

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run CLI
uv run memkith --help

# Run graph visualizer
cd graph_vizualizer && npm install && npm run dev

Repository layout

src/memkith/
  cli.py                 CLI commands (learn, recall, rules, mcp, export-graph, init, login)
  config.py              Configuration loading (.memkith/config.json, env vars, git branch)
  core/memory.py         MCP tool handlers, dedup, similarity, topic resolution, scope wiring
  core/protocols.py      Store interface (abstracts Supabase client for testing)
  graph/models.py        Node, Edge, Graph types and traversal helpers
  graph/snapshot.py      Import/Export JSON (NetworkX node-link format)
  store/client.py        Supabase REST API client
  onboarding.py          Init and login workflows
tests/                   Pytest coverage for graph and memory behavior
graph_vizualizer/        Next.js graph visualization app
supabase/                Database migrations and config
docs/                    Product and architecture docs

Docs

• CHANGELOG.md — implemented features in the current Python/MCP milestone and next items to build
• docs/website-copy.md — marketing-page copy for the multiplayer AI positioning
• docs/product.md — product positioning, memory types, CLI usage, scope hints
• docs/architecture.md — data model, write/read paths, graph hierarchy, storage layer