Insitu

Identidad situada para agentes. Quién eres aquí.

Insitu almacena stanzas reutilizables (secciones de orientación permanente) y las compone en un protocolo para el proyecto en el que estás. materialize escribe ese protocolo en archivos que el host ya inyecta al inicio de la sesión. Puedes redactar con list_stanzas y los resúmenes de tamaño. Los agentes usan resolve_protocol para inspeccionar y extraer las stanzas available.

No modela repositorios, componentes ni hechos del sistema. Eso es una herramienta de contexto de desarrollo (ContextForge, en la configuración de referencia). Se pretende que ambos funcionen lado a lado.

Estado

Diseño bloqueado el 2026-08-17 (DESIGN.md v0.5). La ruta de lectura, los roles (§6.1), validate / where_used y materialize están implementados. Las herramientas de mutación esperan hasta después del primer dogfood. Próximo paso activo: STATUS.md.

Instalación

Requiere Python 3.11+ y uv.

cd insitu
uv sync
uv run pytest
uv run insitu

uv run insitu inicia el servidor MCP en stdio.

Raíz del vault

Un vault por proceso, en este orden:

1. INSITU_HOME

2. --vault /path/to/vault

3. ~/.insitu

Un vault nuevo es solo carpetas en disco (stanzas/, projects/, opcional config/surfaces.yaml). examples/vault/ en este repositorio es una muestra ficticia a la que puedes apuntar:

uv run insitu --vault examples/vault

No copies un vault personal en este repositorio público.

Añadir el servidor MCP a un host

Consulta install/mcp.json.examples.md para fragmentos de Cursor, Claude Code y Grok. Forma típica:

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

Copiar los tres routers (una vez, global al usuario)

Los routers le indican al host que Insitu existe. No son el protocolo del proyecto.

Opcional: pega install/AGENTS.md en un archivo de constitución a mano. materialize nunca escribe AGENTS.md, CLAUDE.md ni CLAUDE.local.md.

Habilita los adaptadores de host en el vault con config/surfaces.yaml (grok, claude, cursor). Luego, desde un checkout del proyecto, llama a materialize. Esto escribe PROTOCOL.md y los archivos de adaptador en .grok/rules/, .claude/rules/ y .cursor/rules/.

Uso previsto

# 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?

Desarrollo

uv sync
uv run pytest
uv run insitu

Python 3.11+, FastMCP. Consulta AGENTS.md si eres un agente que trabaja en este repositorio.

Licencia

MIT. Consulta LICENSE.