PROJECT CONTEXT FOR AI AGENTS

Your codebase.
An open book.

Give your agent a map of the project, the task at hand, and the exact code it needs. Less searching. More building.

Get started Read the docs

Codex · Claude · Cursor · VS Code · MCP

~/workspaceindex ready

EXAMPLE WORKSPACE

workspace_contextlocal

projectacme / api

taskAdd session expiration

locate_codelocal

src/auth/session.ts fresh

24export function verifySession(token) {
25 return token.expiresAt > Date.now();
26}

handler→ calls →verifySession

BUILT FOR YOUR WORKFLOW

Codex

Claude Code

Cursor

VS Code

Windsurf

Antigravity

01 / WORKFLOW

A little context. A lot less guesswork.

From a new session to the right place in your code.

Understand the project

Project purpose, workspace, Git state and a declared objective. Pick up the thread without starting from scratch.

workspace_context

Locate the implementation

Find files and definitions by name or keyword. Get line evidence and a freshness check before editing.

locate_code

Follow the connections

Inspect callers and references. Add hybrid retrieval when you need to search by concept.

callers · find_references

02 / ARCHITECTURE

Three views. One workflow.

System architecture, tool sequence and the developer workflow.

System diagram

Where the context lives.

MCP connects your agent to local files and SQLite. Embeddings and Qdrant extend the system when you need semantic retrieval.

Drawing diagram…

View Mermaid source

flowchart TB
    accTitle: hnindex system architecture
    accDescr: An MCP agent calls a local hnindex server with workspace files and SQLite storage. Semantic retrieval optionally uses embeddings and Qdrant.
    agent_client["AI agent / MCP client<br/>Codex · Claude · Cursor"]
    subgraph local_workspace["Local workspace"]
        hnindex_server["hnindex MCP server<br/>Context · AST · code lookup"]
        project_files["Source files<br/>README · Git"]
        sqlite_store[("SQLite<br/>FTS · graph · declared tasks")]
        project_files -->|Read and check freshness| hnindex_server
        hnindex_server <-->|Index and task storage| sqlite_store
    end
    subgraph semantic_services["Optional semantic retrieval"]
        embedding_provider["Embeddings<br/>Ollama local or cloud API"]
        qdrant_store[("Qdrant vectors<br/>Local or hosted")]
    end
    agent_client <-->|MCP / stdio| hnindex_server
    hnindex_server -.->|Code chunks and queries| embedding_provider
    embedding_provider -.->|Vectors| hnindex_server
    hnindex_server <-.->|Store and retrieve vectors| qdrant_store

Scroll inside the diagram on smaller screens.

Read all three diagrams and explanations

LOCAL FIRST. YOUR CHOICE.

Keep the index close. Choose your embeddings.

SQLite holds project context, keyword search and the code graph. For semantic retrieval, use local Ollama or your preferred cloud embedding API.

Read the docs

SQLite + Code GraphOffline workspace + code locations

LOCAL

Optional semantic searchOllama · OpenAI · Voyage · Gemini · compatible

Cloud embedding providers receive the code chunks you send for embedding.

FROM ZERO TO CONTEXT

Make your next session a little smarter.

Add the MCP server to your editor. Start with an offline code graph, then add semantic search when you need it.

Node 22+ · Graph indexing supports TypeScript and JavaScript · Embeddings are optional for the offline path.

01 / CONNECT

$ npx -y hnindex-cli init --mcp codex

Run inside the project. Codex loads project .codex/config.toml for trusted projects only. Optional skill: npx -y hnindex-cli init-skill --target codex

02 / INDEX LOCALLY

index_code_graph(
  path: "/your/project",
  project_name: "my-app"
)

03 / START THE TASK

workspace_context(project_name: "my-app",
  task: "Add session expiry")
locate_code(project_name: "my-app",
  symbol: "verifySession")

02 / FAQ

A few things to know.

Do I need an embedding API key?

Workspace context and TypeScript/JavaScript code graph navigation work offline. Semantic and hybrid retrieval need your configured embedding provider and Qdrant.

Does my code leave my machine?

Workspace context, keyword lookup and the code graph run locally. Ollama can keep embeddings local too. If you choose a cloud provider, the chunks you embed are sent to that provider.

Will the agent always use hnindex?

MCP startup instructions and the optional editor skill guide the workflow. The client decides which tools to call. Filesystem search remains useful for code that is missing, excluded or stale.

How does it remember what I’m working on?

The agent declares a task through workspace_context. hnindex stores it in SQLite per project and session. Git state provides evidence of changes, not a guess about your intent.

Your codebase.An open book.