Hi everyone, this is my first post on dev.to and I wanted to share a project I've been building.
- Here's the problem I kept running into with Cursor and Claude Code: the AI has no idea why decisions were made in a codebase.
- It suggests refactors that break existing architecture. It recommends libraries I'd already evaluated and rejected.
- It doesn't know my constraints. I ended up re-explaining the same context in every new chat session, and when a new developer joins the project, their AI starts from zero again too.
I built Archie to fix this. One command:
npx archie init
It reads your codebase and git history, uses Gemini to generate a structured ARCHITECTURE.md, and keeps that doc updated automatically via a git post-commit hook. No manual upkeep required.
The doc captures:
- what the project actually does
- why each technology was chosen
- how core flows work, traced through real files
- key decisions and the alternatives you rejected (and why)
- known limitations
End result is that every developer and every AI tool that opens the project gets the same context the original developer had. The AI stops re-suggesting things you already ruled out.
Technical decisions worth discussing
Context window
I went with Gemini specifically for the huge context window
Incremental updates
Archie builds a dependency graph from static import analysis. When files change, it finds their direct imports and importers (basically their neighbors), and only sends those to Gemini — not the whole codebase. Keeps updates fast and cheap per commit.
State management
.git/archie/state.json tracks lastProcessedCommit. The hook grabs ALL commits between the last processed one and HEAD, not just the latest — so it catches changes even if you've made a bunch of commits offline.
Surgical update prompting
There's a Generate mode (first run) and an Update mode (every run after). The update prompt explicitly tells Gemini to only touch the sections affected by the changed files, so anything you've manually written stays untouched.
Significance detection
This is what stops Archie from burning API calls on every tiny commit. It only fires on things like package.json changes, schema/migration files, new directories, or commits touching 5+ files. Smaller commits still move the state pointer forward, just without triggering a regeneration.
Known limitations (being upfront here)
- Import analysis is regex-based, so it misses dynamic imports and re-exports
- No monorepo support yet
- Prompt quality varies on non-TypeScript codebases
It's still early — about 250 npm downloads since launch a few days ago — so I'm still figuring out what's actually useful to people.
- GitHub: https://github.com/abhishek-sonje/archie
- Landing page: https://archie.abhishekdev.tech
- Try it:
npm i archie-ai
I'd genuinely like to hear what you think, whether it's the core premise, the architecture doc format, or any of the technical decisions above. Happy to discuss any of it in the comments.
Top comments (3)
Permanent context is powerful only if it has decay rules. The thing I would watch is how the map handles stale decisions, deprecated modules, and ownership boundaries. A wrong memory can be worse than no memory.
This is the most important tradeoff in the whole project,
Here's what Archie currently does about each concern:
Deprecated modules: deleted files trigger significance detection,
and the update prompt explicitly instructs Gemini to remove
documentation for things that no longer exist in the codebase.
Dependency removals from package.json also always trigger an update.
This handles the code-visible cases.
Stale decisions: this is the honest gap. If a decision becomes
stale for business or organizational reasons, not because of
code changed... Archie has no signal. It only sees what git sees.
A decision documented six months ago that's now wrong but whose
code hasn't changed will stay in the doc until something forces
an update.
Ownership boundaries: not in V1 at all.
Your "wrong memory worse than no memory" point is what I keep
thinking about. My partial answer is that Gemini sees the actual
current code every time it updates... so it's not purely relying
on what was previously written, it can contradict the existing
doc if the code contradicts it. But that only works for
code-visible staleness.
The decay rules idea is genuinely interesting. Something like:
sections older than N commits without a related code change
get flagged as "possibly stale" rather than removed. Would
surface the problem without making wrong decisions.
That is the right honest boundary. Git-visible decay can be automated; business-context decay needs a separate signal. I would probably add a lightweight review clock for high-impact memory: if a decision is old, touches auth/billing/infra, or has no linked owner, the agent should treat it as suspect rather than permanent truth.