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
feat: add ix global command automatically added when ./setup.sh is run. Also changed README.md around and updated it's contents.
kagebinarya90e2b7cbdc4
diff --git a/.gitignore b/.gitignoreindex 40339b56..4eabf48e 100644--- a/.gitignore+++ b/.gitignore@@ -7,3 +7,4 @@ target/.worktrees/ix-cli/node_modules/ix-cli/dist/+.vscode/\ No newline at end of filediff --git a/README.md b/README.mdindex f72a8527..4c482136 100644--- a/README.md+++ b/README.md@@ -1,198 +1,175 @@# 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.+Ix Memory is a local, versioned knowledge graph for codebases.-## What It Does+It has two runtime parts:+- `memory-layer` (Scala HTTP API)+- `ix-cli` (TypeScript CLI; canonical interface)-- **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+MCP is still present for compatibility, but the primary interface is `ix` CLI commands.++## What It Supports Today++- File ingestion: `.py`, `.ts`, `.tsx`, `.scala`, `.sc`, `.json`, `.yaml`, `.yml`, `.toml`, `.md`+- Graph navigation: search, explain, callers/callees, imports/imported-by, contains, depends+- Decision and intent tracking: `ix decide`, `ix decisions`, `ix truth ...`+- Provenance + history: `ix patches`, `ix history`, `ix diff`, `ix conflicts`+- GitHub ingestion: `ix ingest --github owner/repo` (issues/PRs/commits/comments)## 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` |+| Tool | Version |+|---|---|+| Java | 17+ |+| sbt | 1.x |+| Docker | 20+ |+| Node.js | 18+ |+| npm | 9+ |-## Quickstart+## Install And Start-### 1. Start the backend+### Recommended (one command)-```bash-# Production mode (Docker handles everything)-./stack.sh+From repo root:-# Or dev mode (ArangoDB in Docker, Memory Layer via sbt for hot reload)-./dev.sh-cd memory-layer && sbt run # in another terminal+```bash+./setup.sh```-The backend is ready when you see:+What this does:+- Starts backend services (`arangodb` + `memory-layer`) via `scripts/backend.sh`+- Builds CLI (`ix-cli`) via `scripts/build-cli.sh`+- Installs a global `ix` command at `~/.local/bin/ix`+- Ensures `~/.local/bin` is on your PATH in `~/.bashrc` / `~/.zshrc`++Optional flags:++```bash+./setup.sh --skip-backend+./setup.sh --skip-global-ix```-Ix Memory backend is ready at http://localhost:8090++### Verify++```bash+./scripts/backend.sh check+ix status```-### 2. Install CLI dependencies+## Running The CLI++`setup.sh` installs `ix` globally for your user at `~/.local/bin/ix`.```bash-cd ix-cli && npm install+ix status```-### 3. Initialize Ix in your project+If `ix` is not found in your current shell, reload your shell or run:```bash-cd /path/to/your/project-npx tsx /path/to/ix-cli/src/cli/main.ts init+export PATH="$HOME/.local/bin:$PATH"```-This checks the backend is running, creates `~/.ix/config.yaml`, and adds Ix rules to your `CLAUDE.md`.+## Connect A Project-### 4. Ingest your codebase+### Fast path```bash-ix ingest ./src --recursive+./scripts/connect.sh /path/to/your/project```-### 5. Explore+This configures project files and ingests code.++### Manual path```bash-ix search "UserService" --kind class-ix explain UserService-ix callers UserService+cd /path/to/your/project+node /path/to/IX-Memory/ix-cli/dist/cli/main.js init+node /path/to/IX-Memory/ix-cli/dist/cli/main.js ingest ./src --recursive```-## CLI Commands--All commands accept `--format json` for machine-readable output.+## Core Usage-### Core+All commands support `--format json`.-| Command | Usage | Description |-|---------|-------|-------------|-| `ix status` | `ix status` | Check backend health |-| `ix ingest` | `ix ingest <path> [--recursive]` | Ingest source files |-| `ix ingest --github` | `ix ingest --github owner/repo` | Ingest GitHub issues, PRs, commits |-| `ix search` | `ix search <term> [--limit N]` | Search nodes by term |-| `ix explain` | `ix explain <symbol>` | Understand an entity |-| `ix callers` | `ix callers <symbol>` | What calls a function |-| `ix callees` | `ix callees <symbol>` | What a function calls |-| `ix contains` | `ix contains <symbol>` | Members of a class/module |-| `ix imports` | `ix imports <symbol>` | What an entity imports |-| `ix depends` | `ix depends <symbol>` | Dependency impact analysis |-| `ix text` | `ix text <term>` | Fast lexical search (ripgrep) |-| `ix read` | `ix read <target>` | Read source code |-| `ix locate` | `ix locate <symbol>` | Find a symbol (graph + text) |-| `ix query` | `ix query <question> --unsafe` | [DEPRECATED] Broad graph query |+```bash+ix status+ix ingest ./src --recursive+ix search IngestionService --kind class --format json+ix explain IngestionService --format json+ix callers parseFile --format json+ix callees parseFile --format json+ix imports IngestionService --format json+ix imported-by IngestionService --format json+ix contains IngestionService --format json+ix depends IngestionService --depth 2 --format json+ix read src/main/scala/ix/memory/Main.scala:1-80+ix text "commitPatch" --language ts --limit 20 --format json+```-### Decisions & Intents+## GitHub Ingestion-| 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 |+```bash+ix ingest --github owner/repo --since 2026-01-01 --limit 50 --format json+```-### Inspection+Auth resolution order in code:+1. `--token <pat>`+2. `GITHUB_TOKEN`+3. `gh auth token`-| 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 |+## Useful Scripts-### Setup+| Script | Purpose |+|---|---|+| `./setup.sh` | Start backend + build CLI + install global `ix` |+| `./scripts/backend.sh up` | Start backend |+| `./scripts/backend.sh down` | Stop backend |+| `./scripts/backend.sh logs` | Tail logs |+| `./scripts/backend.sh clean` | Remove volumes/data |+| `./scripts/build-cli.sh` | Build CLI |+| `./scripts/connect.sh <dir>` | Connect project + ingest |+| `./scripts/disconnect.sh <dir>` | Remove project config |+| `./scripts/ingest.sh [path]` | Ingest helper |-| 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) |+## Testing-## MCP Integration (Compatibility Only)+CLI:-> **Note:** The CLI is now the canonical agent interface. MCP is retained for backward compatibility but is no longer the recommended integration path. Use `ix` CLI commands with `--format json` instead.+```bash+cd ix-cli+npm test+```-MCP server installation is still available if needed:+Backend:```bash-ix mcp-install --claude-code # Claude Code-ix mcp-install --cursor # Cursor-ix mcp-install # Claude Desktop+# Requires ArangoDB running on localhost:8529+sbt memoryLayer/test```+## Known Gaps / Notes++- Many Scala tests require a live ArangoDB instance; if it is down, DB/API/E2E specs fail.+- `TreeSitterPythonParser` still contains a TODO for full AST traversal fallback behavior.+- `ix query` remains available but is explicitly deprecated in help text and templates.+- `connect.sh` still sets MCP config for IDE compatibility; CLI is still the canonical interface.++## Next Steps (Recommended)++1. Stabilize backend tests by making DB-dependent specs self-start ArangoDB (or isolate with test profile).+2. Resolve `ConflictDetectorSpec` expectation drift (`"Contradictory"` vs `"Potential inconsistency"`).+3. Add a CI pipeline that runs `npm test` and `sbt memoryLayer/test` with Arango service container.+4. Add parser diagnostics reporting in CLI output when fallback/unresolved references are returned.+## Architecture```- ┌──────────────────┐ ┌───────────┐-┌─────────────┐ │ Memory Layer │────>│ ArangoDB │-│ ix CLI │───>│ (Scala/http4s) │ │ (Graph) │-│ (canonical)│ └──────────────────┘ └───────────┘-└─────────────┘ ▲- ┌────────┘- │- ┌─────┴───────┐- │ MCP Server │ (compatibility only)- └─────────────┘+ix-cli ---> memory-layer (http4s) ---> ArangoDB+ \+ \--> mcp server (compatibility mode)```-- **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 |-## LicenseProprietary — IX Infrastructure.diff --git a/ix-cli/package-lock.json b/ix-cli/package-lock.jsonindex d6ceeb2e..98e8d1a9 100644--- a/ix-cli/package-lock.json+++ b/ix-cli/package-lock.json@@ -1547,12 +1547,12 @@}},"node_modules/express-rate-limit": {- "version": "8.2.1",- "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.2.1.tgz",- "integrity": "sha512-PCZEIEIxqwhzw4KF0n7QF4QqruVTcF73O5kFKUnGOyjbCCgizBBiFaYpd/fnBLUMPw/BWw9OsiN7GgrNYr7j6g==",+ "version": "8.3.0",+ "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.3.0.tgz",+ "integrity": "sha512-KJzBawY6fB9FiZGdE/0aftepZ91YlaGIrV8vgblRM3J8X+dHx/aiowJWwkx6LIGyuqGiANsjSwwrbb8mifOJ4Q==","license": "MIT","dependencies": {- "ip-address": "10.0.1"+ "ip-address": "10.1.0"},"engines": {"node": ">= 16"@@ -1820,9 +1820,9 @@"license": "ISC"},"node_modules/ip-address": {- "version": "10.0.1",- "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.0.1.tgz",- "integrity": "sha512-NWv9YLW4PoW2B7xtzaS3NCot75m6nK7Icdv0o3lfMceJVRfSoQwqD4wEH5rLwoKJwUiZ/rfpiVBhnaF0FK4HoA==",+ "version": "10.1.0",+ "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",+ "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==","license": "MIT","engines": {"node": ">= 12"diff --git a/setup.sh b/setup.shindex 29904083..c0c68110 100755--- a/setup.sh+++ b/setup.sh@@ -10,24 +10,70 @@ set -euo pipefail# To connect a project, run: ./scripts/connect.sh ~/my-project## Usage:-# ./setup.sh # Start backend + build CLI-# ./setup.sh --skip-backend # Just build CLI (backend already running)+# ./setup.sh # Start backend + build CLI + install global ix command+# ./setup.sh --skip-backend # Just build CLI + install global ix command+# ./setup.sh --skip-global-ix # Skip installing global ix command# ─────────────────────────────────────────────────────────────────────────────IX_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"SKIP_BACKEND=false+SKIP_GLOBAL_IX=false++ensure_local_bin_on_path() {+ local path_line='export PATH="$HOME/.local/bin:$PATH"'+ local rc_files=()++ if [ -f "$HOME/.bashrc" ]; then+ rc_files+=("$HOME/.bashrc")+ fi+ if [ -f "$HOME/.zshrc" ]; then+ rc_files+=("$HOME/.zshrc")+ fi+ if [ "${#rc_files[@]}" -eq 0 ]; then+ rc_files=("$HOME/.bashrc")+ fi++ for rc in "${rc_files[@]}"; do+ if [ ! -f "$rc" ]; then+ touch "$rc"+ fi+ if ! grep -Fq "$path_line" "$rc"; then+ echo "" >> "$rc"+ echo "# Added by IX-Memory setup" >> "$rc"+ echo "$path_line" >> "$rc"+ fi+ done+}++install_global_ix() {+ local local_bin="$HOME/.local/bin"+ local ix_shim="$local_bin/ix"+ local ix_entry="$IX_DIR/ix-cli/dist/cli/main.js"++ mkdir -p "$local_bin"++ cat > "$ix_shim" <<EOF+#!/usr/bin/env bash+exec node "$ix_entry" "\$@"+EOF+ chmod +x "$ix_shim"++ ensure_local_bin_on_path+}while [[ $# -gt 0 ]]; docase "$1" in--skip-backend) SKIP_BACKEND=true; shift ;;+ --skip-global-ix) SKIP_GLOBAL_IX=true; shift ;;-h|--help)echo "Usage: ./setup.sh [OPTIONS]"echo ""- echo "Starts the IX-Memory backend and builds the CLI."+ echo "Starts the IX-Memory backend, builds the CLI, and installs an 'ix' command."echo ""echo "Options:"echo " --skip-backend Skip backend startup (if already running)"+ echo " --skip-global-ix Skip installing ~/.local/bin/ix shim"echo " -h, --help Show this help"echo ""echo "After setup, connect a project:"@@ -74,6 +120,17 @@ echo ""echo "── [2] Build CLI ──────────────────────────────────""$IX_DIR/scripts/build-cli.sh"+# ── Step 3: Install Global ix Command ───────────────────────────────────────++echo ""+echo "── [3] Global ix command ──────────────────────────"+if [ "$SKIP_GLOBAL_IX" = true ]; then+ echo " (skipped via --skip-global-ix)"+else+ install_global_ix+ echo " [ok] Installed: ~/.local/bin/ix"+fi+# ── Done ─────────────────────────────────────────────────────────────────────echo ""@@ -84,6 +141,9 @@ echo ""echo " Backend: http://localhost:8090"echo " ArangoDB: http://localhost:8529"echo ""+echo " CLI: ix status"+echo " (open a new shell, or run: export PATH=\"\$HOME/.local/bin:\$PATH\")"+echo ""echo " Next: connect a project to IX:"echo " ./scripts/connect.sh ~/my-project"echo ""