context: build local-first institutional memory with an MCP surface

[guicybercode]

Context

The project can become more than a terminal manager by providing agents with inspectable local knowledge about repositories, instructions, decisions, ownership, dependencies, and previous task outcomes.

Goal

Build a local-first context index and read-only MCP server for engineering knowledge.

Initial sources

• README and project documentation;
• ADRs;
• AGENTS.md and vendor instruction files;
• repository metadata and Git history;
• task notes and completed task summaries;
• manually configured service ownership and dependency metadata.

MCP tool candidates

• search_docs;
• get_project;
• get_owner;
• get_dependencies;
• search_tasks;
• get_architecture_decision;
• search_code_metadata.

Acceptance criteria

• Indexing is opt-in per project and works without cloud services.
• Every result includes source path/entity, revision, timestamp, and freshness.
• Deleted or moved sources are reconciled incrementally.
• Secrets, ignored files, env data, PTY output, and unsupported paths are excluded by default.
• Agents receive only context authorized for their current task/project.
• MCP tools are read-only in the first version.
• Index size, query time, and result count are bounded.
• Users can inspect, rebuild, disable, and delete the local index.
• Tests cover stale documents, ignored files, permission boundaries, and provenance.

Out of scope

Jira, Slack, Confluence, Notion, cloud embeddings, and cross-company search.

[BrierAinz]

This shape looks strong. I would add one acceptance criterion that tends to decide whether a local-first context index stays trustworthy over time:

• each returned result should include not only provenance, but also the exclusion reason if a nearby expected source was intentionally skipped.

For example, if AGENTS.md was indexed but .env, PTY logs, ignored files, or an unsupported path were skipped, an inspect/rebuild command should be able to show that as a bounded audit receipt. That makes "no result" distinguishable from "not indexed yet", "deleted", "ignored by policy", and "outside authorized scope".

For the first MCP version, I would also keep the tool surface narrow and policy-testable:

• search_docs(query, project_scope)
• get_source(path_or_id)
• explain_index(project_scope)

explain_index is the quiet workhorse: it can report index freshness, source counts, skipped-source classes, size bounds, and last rebuild outcome without exposing raw secrets or unsupported paths. Agents then have a way to know whether their context is current enough before acting on it.