Insitu

Situated identity for agents. Who you are here.

Insitu stores reusable stanzas (sections of standing guidance) and composes them into a protocol for the project you are standing in. materialize writes that protocol into files the host already injects at session start. You author with list_stanzas and the size summaries. Agents use resolve_protocol to inspect and to pull available stanzas.

It does not model repos, components, or system facts. That is a dev-context tool (ContextForge, in the reference setup). The two are meant to run side by side.

Status

Design locked 2026-08-17 (DESIGN.md v0.5). The read path, roles (§6.1), validate / where_used, and materialize are implemented. Mutation tools wait until after first dogfood. Live next-step: STATUS.md.

Installation

Requires Python 3.11+ and uv.

cd insitu
uv sync
uv run pytest
uv run insitu

uv run insitu starts the MCP server on stdio.

Vault root

One vault per process, in this order:

1. INSITU_HOME

2. --vault /path/to/vault

3. ~/.insitu

A fresh vault is just folders on disk (stanzas/, projects/, optional config/surfaces.yaml). examples/vault/ in this repo is a fictional sample you can point at:

uv run insitu --vault examples/vault

Do not copy a personal vault into this public repo.

Add the MCP server to a host

See install/mcp.json.examples.md for Cursor, Claude Code, and Grok snippets. Typical shape:

{
  "mcpServers": {
    "insitu": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/insitu", "insitu"],
      "env": { "INSITU_HOME": "/path/to/your/vault" }
    }
  }
}

Copy the three routers (once, user-global)

Routers tell the host that Insitu exists. They are not the project protocol.

Optional: paste install/AGENTS.md into a constitution file by hand. materialize never writes AGENTS.md, CLAUDE.md, or CLAUDE.local.md.

Enable host adapters in the vault with config/surfaces.yaml (grok, claude, cursor). Then from a project checkout call materialize. That writes PROTOCOL.md plus the adapter files under .grok/rules/, .claude/rules/, and .cursor/rules/.

Intended use

# you, after a vault or map change
materialize               # PROTOCOL.md + host adapters (.grok/.claude/.cursor rules)

# agent, live / on demand
resolve_protocol          # inspect weight, refresh, compare to the materialized header
get_stanza ...            # pull an available stanza

# you, registering a new project
list_stanzas              # what exists, and how heavy each piece is
link_stanza ...           # after the write path exists
get_project               # how heavy is this project's protocol?

Develop

uv sync
uv run pytest
uv run insitu

Python 3.11+, FastMCP. See AGENTS.md if you are an agent working in this repo.

License

MIT. See LICENSE.