Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
docs: add README with quickstart, CLI reference, and architecture
riley02276bf83ffcca0f
diff --git a/README.md b/README.mdnew file mode 100644index 00000000..d1089b98--- /dev/null+++ b/README.md@@ -0,0 +1,221 @@+# Ix Memory++Persistent, time-aware memory for LLM coding assistants. Ix builds a versioned knowledge graph from your codebase and gives LLMs structured context with confidence scores — so they answer from facts, not training data.++## What It Does++- **Ingests** source files (Python, TypeScript, YAML, JSON, TOML, Markdown) into a knowledge graph+- **Queries** return structured context: nodes, edges, claims, conflicts, and decisions — each with 6-factor confidence scores+- **Tracks decisions** with rationale linked to project intents, so future sessions know *why* things were built+- **Detects conflicts** when the graph contains contradictory claims+- **Versions everything** — every change is a patch with provenance, so you can diff and time-travel++## Prerequisites++| Tool | Version | Check |+|------|---------|-------|+| Java | 17+ | `java -version` |+| sbt | 1.x | `sbt --version` |+| Docker | 20+ | `docker --version` |+| Node.js | 18+ | `node --version` |+| npm | 9+ | `npm --version` |++## Quickstart++### 1. Start the backend++```bash+# Production mode (Docker handles everything)+./stack.sh++# Or dev mode (ArangoDB in Docker, Memory Layer via sbt for hot reload)+./dev.sh+cd memory-layer && sbt run # in another terminal+```++The backend is ready when you see:+```+Ix Memory backend is ready at http://localhost:8090+```++### 2. Install CLI dependencies++```bash+cd ix-cli && npm install+```++### 3. Initialize Ix in your project++```bash+cd /path/to/your/project+npx tsx /path/to/ix-cli/src/cli/main.ts init+```++This checks the backend is running, creates `~/.ix/config.yaml`, and adds Ix rules to your `CLAUDE.md`.++### 4. Ingest your codebase++```bash+ix ingest ./src --recursive+```++### 5. Query++```bash+ix query "What does the UserService class do?"+```++## CLI Commands++All commands accept `--format json` for machine-readable output.++### Core++| Command | Usage | Description |+|---------|-------|-------------|+| `ix status` | `ix status` | Check backend health |+| `ix query` | `ix query <question>` | Query the knowledge graph |+| `ix ingest` | `ix ingest <path> [--recursive]` | Ingest source files |+| `ix search` | `ix search <term> [--limit N]` | Search nodes by term |++### Decisions & Intents++| Command | Usage | Description |+|---------|-------|-------------|+| `ix decide` | `ix decide <title> --rationale <text> [--intent-id <id>]` | Record a design decision |+| `ix truth list` | `ix truth list` | List all project intents |+| `ix truth add` | `ix truth add <statement> [--parent <id>]` | Add a project intent/goal |++### Inspection++| Command | Usage | Description |+|---------|-------|-------------|+| `ix entity` | `ix entity <id>` | Get entity details (node, claims, edges) |+| `ix history` | `ix history <entityId>` | Show provenance chain for an entity |+| `ix patches` | `ix patches` | List recent patches |+| `ix diff` | `ix diff <fromRev> <toRev> --entity <id>` | Show changes between revisions |+| `ix conflicts` | `ix conflicts` | List detected conflicts |++### Setup++| Command | Usage | Description |+|---------|-------|-------------|+| `ix init` | `ix init [--force]` | Initialize Ix in the current project |+| `ix mcp-install` | `ix mcp-install [--cursor\|--claude-code]` | Install MCP server config |+| `ix mcp-start` | `ix mcp-start` | Start the MCP server (stdio) |++## MCP Integration++Ix exposes 13 tools and 2 resources over the [Model Context Protocol](https://modelcontextprotocol.io/), so LLMs can query, ingest, and record decisions automatically.++### Claude Code++```bash+ix mcp-install --claude-code+```++### Cursor++```bash+ix mcp-install --cursor+```++### Claude Desktop++```bash+ix mcp-install+```++### MCP Tools++| Tool | Description |+|------|-------------|+| `ix_query` | Query the knowledge graph (ALWAYS call before answering codebase questions) |+| `ix_ingest` | Ingest files into the graph (call IMMEDIATELY after file changes) |+| `ix_decide` | Record a design decision with rationale |+| `ix_search` | Search nodes by term |+| `ix_entity` | Get full entity details |+| `ix_expand` | Expand a node's neighborhood |+| `ix_history` | Get provenance chain |+| `ix_truth` | Manage project intents |+| `ix_diff` | Diff between revisions |+| `ix_conflicts` | List conflicts |+| `ix_resolve` | Resolve a conflict |+| `ix_assert` | Assert a claim about an entity |+| `ix_patches` | List or get patches |++### MCP Resources++| URI | Description |+|-----|-------------|+| `ix://session/context` | Current session working set (entities queried, decisions made) |+| `ix://project/intent` | Project intent tree |++## Architecture++```+┌─────────────┐ ┌──────────────────┐ ┌───────────┐+│ ix CLI │────>│ Memory Layer │────>│ ArangoDB │+│ (TypeScript)│ │ (Scala/http4s) │ │ (Graph) │+└─────────────┘ └──────────────────┘ └───────────┘+ │+┌──────┴──────┐+│ MCP Server │ (stdio transport, same TypeScript codebase)+│ 13 tools │+│ 2 resources│+└─────────────┘+```++- **Memory Layer** — Scala 2.13, Cats Effect 3, http4s 0.23, Circe. Handles ingestion, parsing, graph operations, context assembly with 6-factor confidence scoring.+- **CLI + MCP** — TypeScript, Commander, MCP SDK. Thin client that talks to the Memory Layer REST API.+- **ArangoDB** — Multi-model database used as the graph store. All nodes, edges, claims, and patches stored here.++## Supported File Types++| Extension | Parser | What It Extracts |+|-----------|--------|------------------|+| `.py` | Tree-sitter | Modules, classes, functions, imports, calls |+| `.ts`, `.tsx` | Regex | Classes, functions, interfaces, imports, calls |+| `.json`, `.yaml`, `.yml`, `.toml` | Config | Config entries, nested keys, values |+| `.md` | Markdown | Document sections by heading hierarchy |++## Confidence Scoring++Every claim returned by `ix query` includes a 6-factor confidence breakdown:++| Factor | What It Measures |+|--------|-----------------|+| **Base Authority** | Source type weight (code > config > docs > inferred) |+| **Verification** | Whether the claim has been independently verified |+| **Recency** | How recently the source was observed |+| **Corroboration** | How many independent sources confirm the claim |+| **Conflict Penalty** | Reduction if the claim is part of a detected conflict |+| **Intent Alignment** | Whether the claim connects to a stated project goal |++Final score = `base × verification × recency × corroboration × conflict_penalty × intent_alignment`++## Scripts++| Script | Description |+|--------|-------------|+| `./stack.sh` | Build JAR + start full stack via Docker Compose |+| `./stack.sh down` | Stop the stack |+| `./stack.sh clean` | Stop + remove data volumes |+| `./stack.sh logs` | Tail container logs |+| `./dev.sh` | Start only ArangoDB (for dev — run `sbt run` separately) |+| `./dev.sh down` | Stop ArangoDB |++## Environment Variables++| Variable | Default | Description |+|----------|---------|-------------|+| `IX_ENDPOINT` | `http://localhost:8090` | Memory Layer URL (used by CLI and MCP) |+| `ARANGO_HOST` | `localhost` | ArangoDB host |+| `ARANGO_PORT` | `8529` | ArangoDB port |+| `ARANGO_DATABASE` | `ix_memory` | ArangoDB database name |+| `ARANGO_USER` | `root` | ArangoDB user |+| `ARANGO_PASSWORD` | (empty) | ArangoDB password |++## License++Proprietary — IX Infrastructure.