Metadata-Version: 2.4
Name: memkith
Version: 0.1.0b1
Summary: Multiplayer context for AI coding agents
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: fastembed>=0.4
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: pyjwt>=2.8
Requires-Dist: python-dotenv>=1.0
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# 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`](https://docs.astral.sh/uv/).

```bash
# 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):

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

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

```bash
# 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:

```text
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

```bash
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:

```bash
# 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:

```bash
# 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.

```bash
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:

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

### Export and visualization

Export the knowledge graph and visualize it interactively:

```bash
# 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)

```bash
# 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

```text
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](CHANGELOG.md) — implemented features in the current Python/MCP milestone and next items to build
- [docs/website-copy.md](docs/website-copy.md) — marketing-page copy for the multiplayer AI positioning
- [docs/product.md](docs/product.md) — product positioning, memory types, CLI usage, scope hints
- [docs/architecture.md](docs/architecture.md) — data model, write/read paths, graph hierarchy, storage layer
