Getting started

Five steps from clone to a knowledge graph populated from your last week of chats.

Prerequisites

Node.js 20+ (24 also supported)
Ollama running locally — https://ollama.com
One AI agent that writes transcripts somewhere you can read (Cursor, Claude Code, Codex CLI, or VS Code with Copilot)

1. Install

git clone https://github.com/tienan92it/CodeGps
cd CodeGps
npm install
npm run build
npm link              # exposes `codegps` on $PATH

Verify:

codegps --version     # 0.1.0
codegps agents list   # 14 chat agents + dedupe

2. Local LLM

Without a local LLM, only the deterministic syntax pass runs. The agent layers (triage, extractors, clusterer, summarizer, linker, verifier) stay empty. This is intentional — no regex pretends to understand meaning.

Pull the default three models:

ollama pull qwen3:4b-instruct      # classifier — triage, intent, clusterer
ollama pull qwen2.5:14b            # extractor — decision, business logic, summarizer
ollama pull qwen3-embedding:0.6b   # embeddings — dedupe, clustering

Combined hot footprint: ~12.5 GB. Fits on a 24 GB unified-memory Mac. For smaller machines, see configuration → hardware budgets.

Keep them warm between agent calls:

launchctl setenv OLLAMA_KEEP_ALIVE 30m
launchctl setenv OLLAMA_MAX_LOADED_MODELS 3
# restart Ollama after these

3. Init a project

cd /path/to/your/project
codegps init

This creates:

your-project/.codegps/
├── code.db          # L0 — code structure
├── knowledge.db     # L1 → L3 + L2.5 — conversations, facts, domain, concepts
└── config.json      # per-project agent overrides (empty by default)

~/.codegps/
├── global.db        # L4 links + L5 skill graph + project registry
└── config.json      # global defaults

4. Index code + ingest conversations

L0 — code structure

codegps sync

Walks the project honoring .gitignore, parses every supported file with tree-sitter (or the SQL DDL regex parser), writes symbols + edges to code.db. Incremental by content hash — re-running only re-parses changed files.

L1 → L3 + L2.5 — conversations through concepts and domain

codegps ingest

This runs the full pipeline:

Discover sessions from every configured adapter (Cursor / Claude Code / Codex / Copilot)
Read new turns incrementally (per-session byte offset)
Segment each session into windows on user-turn boundaries
Syntax pass on each window (paths, code blocks, shell commands, URLs, ticket IDs)
Triage each window — drop noise, keep signal
Dedupe kept windows by embedding similarity
Extract facts via Decision / BusinessLogic / Intent / ProblemSolution agents (routed by triage domain)
Cluster each new fact into a concept; Summarize affected concepts
Enrich (L2.5) — manifests + SQL → entities/skills, reconcile stated ↔ structural, classify industry, detect gaps

ingest is incremental — only new windows are processed. Use codegps ingest --reprocess after a model swap or interrupted run to re-pass every window; --no-enrich skips step 9.

L4 → L5 — cross-project links + the second brain

codegps link          # export concepts + skills to global.db, link across repos
codegps profile       # industries + top skills across all projects
codegps skills --cross # skills demonstrated in more than one project

5. Inspect the result

codegps status .

# CodeGps status
#   Project: /your/project
#   L0 code:
#     files:   142
#     nodes:   2,041
#     edges:   3,177
#   L1 conversations:
#     sessions: 24
#     turns:    487
#   L1.5 triage:
#     windows:  93
#     triaged:  93  (kept=71, dropped=22)
#   L2 facts:     128
#   L2.5 domain:
#     entities:      8
#     relationships: 11
#     knowledge gaps: 2
#   By scope:    technical 34  industry 9  untagged 85
#   By grounding: stated 96  structural 24  corroborated 8
#   L3 concepts:  31
#   Agent runs:   254

Inspect what got dropped vs kept and why:

codegps triage audit --dropped

Generate canvases (open in Cursor's canvas pane):

codegps canvas triage-audit
codegps canvas project-map
codegps canvas decision-timeline
codegps canvas business-logic

Or query the graph directly:

sqlite3 .codegps/knowledge.db \
  "SELECT kind, title FROM k_nodes WHERE kind='decision' ORDER BY confidence DESC LIMIT 10;"

Troubleshooting

Symptom	Cause & fix
`L0 code: 0 files` after sync	Project has no files in supported languages. Check supported languages.
`L1 conversations: 0 sessions`	No agent has written transcripts for this project path yet. Run the agent against the project once, then re-ingest.
`L3 concepts: 0` while facts > 0	Embedding model not reachable. Check `ollama list` and that `~/.codegps/config.json` points at it.
`triage` labels everything `unknown` with confidence 0.1	Triage Agent call failed — Ollama down or wrong model name. Check `ollama serve` and the `agent_runs` table for the error column.
enrichment / skills / industry all zero on a frontier backend	Agent calls are failing. Query `SELECT agent_name, ok, error FROM agent_runs WHERE ok=0`. A `requires apiKey` error means a raw key was pasted into `apiKeyEnv` (use `apiKey`, or set the env var); a `400` means a wrong model slug.
`enrich` reports zeros on a re-run	Expected — the report counts rows added this run. The data already exists; check `codegps status` for totals. Use `codegps ingest --reprocess` to force a full re-pass.
`Dependencies: 0` in a monorepo	Manifests live in subdirectories — the parser walks nested folders (skipping `node_modules` / `build` / …). If still zero, the manifest format may be unsupported; open an issue.
`codegps: command not found`	You skipped `npm link`. Either run it now, or invoke `node dist/cli/index.js` directly.

Next: architecture → or cli reference →.