Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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/.gitignore
index 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 file
diff --git a/README.md b/README.md
index 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 |
-
## License
Proprietary — IX Infrastructure.
diff --git a/ix-cli/package-lock.json b/ix-cli/package-lock.json
index 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.sh
index 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 ]]; do
case "$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 ""