Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

Merge branch 'feature/ix-redesign' of https://github.com/ix-infrastructure/IX-Memory into feature/ix-redesign

kagebinaryf3f3d989e977
diff --cc README.md
index 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
```