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
Merge branch 'feature/ix-redesign' of https://github.com/ix-infrastructure/IX-Memory into feature/ix-redesign
kagebinaryf3f3d989e977
diff --cc README.mdindex 4c482136,8c1c74e7..da5b00ea--- a/README.md+++ b/README.md@@@ -18,150 -12,128 +18,174 @@@ MCP is still present for compatibility## 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+ |++## Install And Start-## Quickstart+### Recommended (one command)-### 1. Start the backend+From repo root:++```bash+./setup.sh+```++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+ # 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 the CLI++ **Via Homebrew (recommended):**+ ```bash+ brew tap ix-infrastructure/ix https://github.com/ix-infrastructure/IX-Memory+ brew install ix+ ```++ **Or manually:**-```bash-cd ix-cli && npm install && npm run build+./setup.sh --skip-backend+./setup.sh --skip-global-ix```-### 3. Initialize Ix in your project+### Verify```bash-ix init+./scripts/backend.sh check+ix status```-This checks the backend is running, creates `~/.ix/config.yaml`, and adds Ix rules to your `CLAUDE.md`.+## Running The CLI-### 4. Ingest your codebase+`setup.sh` installs `ix` globally for your user at `~/.local/bin/ix`.```bash-ix ingest ./src --recursive+ix status```-### 5. Explore+If `ix` is not found in your current shell, reload your shell or run:```bash-ix search "UserService" --kind class-ix explain UserService-ix callers UserService+export PATH="$HOME/.local/bin:$PATH"```-## CLI Commands+## Connect A Project-All commands accept `--format json` for machine-readable output.+### Fast path-### Core+```bash++cd ix-cli && npm install && npm run build+./scripts/connect.sh /path/to/your/project+```-| 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 |+This configures project files and ingests code.-### Decisions & Intents+### Manual path-| 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 init+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+```-### Inspection+## Core Usage-| 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 |+All commands support `--format json`.-### Setup+```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+```-| 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) |+## GitHub Ingestion-## MCP Integration (Compatibility Only)+```bash+ix ingest --github owner/repo --since 2026-01-01 --limit 50 --format json+```-> **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.+Auth resolution order in code:+1. `--token <pat>`+2. `GITHUB_TOKEN`+3. `gh auth token`-MCP server installation is still available if needed:+## Useful Scripts++| 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 |++## Testing++CLI:```bash-ix mcp-install --claude-code # Claude Code-ix mcp-install --cursor # Cursor-ix mcp-install # Claude Desktop+cd ix-cli+npm test```+Backend:++```bash+# 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```