DEV Community

Ivan
Ivan

Posted on

I built an open-source repo-local context layer for AI coding agents

#ai #programming #opensource #devops

![Technical diagram of .knowledge showing the first-read path, routing bundle, trust and freshness signals, repair queue, source/tests verification, and Inspector workflow.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/veuzfx2iulk2dtre09m2.png)

AI coding agents are getting better at editing code, but they still often start every session like they have never seen the repository before.

They read the README.

Then package files.

Then random source folders.

Then tests.

Then old notes.

Then maybe the same files again in the next session.

That repeated orientation is not only a token problem. It is a trust problem.

The agent does not know which summary is current, which module is stale, which files are risky, or which part of the repo should be checked before editing behavior.

So I built .knowledge — an open-source, repo-local context layer for AI coding agents.

GitHub: https://github.com/pro2pilot/knowledge

What it does

.knowledge gives agents a local first-read path inside the repository:

.knowledge/Quick-Start.md
        ↓
.knowledge/maintenance/routing_bundle.json
        ↓
module cards / evidence / trust state / repair queue
        ↓
current source and tests
Enter fullscreen mode Exit fullscreen mode

The point is not to make agents read less source code.

The point is to stop making them spend the first part of every session rediscovering the same project shape.

The core idea

A coding agent should not treat repo memory as magic.

It should have a clear source-of-truth order:

current source code
current tests
evidence
module cards
decisions
wiki
session notes
external memory
Enter fullscreen mode Exit fullscreen mode

If the task touches auth, billing, runtime execution, queues, storage, secrets, migrations, security, concurrency, or anything stale/suspect/low-confidence, the agent must re-read source and tests.

.knowledge is a routing layer, not a replacement for code review.

What ships in the open core

The repository includes:

agent-integrations/        # Codex, Claude Code, OpenCode
docs/cookbook/             # operational recipes
github-action-templates/   # health, PR summary, evaluation
inspector/                 # local static visual inspector
tools/                     # scan, import, release, metrics
Quick-Start.md             # first-read contract for agents
Enter fullscreen mode Exit fullscreen mode

Some runtime artifacts are generated after setup, for example:

.knowledge/maintenance/routing_bundle.json
.knowledge/maintenance/trust_report.json
.knowledge/maintenance/repair_queue.json
.knowledge/search/index.json
.knowledge/inspector/index.html
Enter fullscreen mode Exit fullscreen mode

That is intentional. A fresh public archive ships the framework, tools, templates, docs, and seed files. Your repo generates its own local state.

Example setup 

node .knowledge/tools/install-agent-integrations.js
node .knowledge/tools/flow.js import
node .knowledge/tools/flow.js release --no-color
Enter fullscreen mode Exit fullscreen mode

After that, the agent has a maintained first-read path instead of inventing a new onboarding route every session.

Why I made it

I do not think the problem is “agents need one more long prompt”.

The problem is that repo context is usually scattered across:

  • chat history
  • README sections
  • stale architecture notes
  • local scratch files
  • hidden agent memory
  • repeated repo crawls

That makes the workflow hard to review.

.knowledge keeps the context beside the code, where it can be versioned, inspected, refreshed, and challenged.

Who this is for

This is mainly for teams or solo builders already using coding agents such as Codex, Claude Code, OpenCode, or custom local agents.

It is probably overkill for very small repos.

It is more useful when:

  • agents repeatedly re-read the same repo structure
  • multiple agents touch the same codebase
  • session handoff matters
  • stale summaries cause wrong-file edits
  • AI-assisted PRs need clearer impact boundaries
  • you want local-first context without required cloud memory

What I would like feedback on

I am looking for feedback from people who already use coding agents in real repositories:

  1. Would you use a repo-local routing bundle as the agent’s first read?
  2. What would you want in a trust/freshness report?
  3. Would a local visual Inspector help your review workflow?
  4. Which agent workflows should be supported first: Codex, Claude Code, OpenCode, or something else?

GitHub repo: https://github.com/pro2pilot/knowledge

Technical notes: https://pro2pilot.com/knowledge/repo-local-knowledge-routing/

Product hub: https://pro2pilot.com/knowledge/

Top comments (0)