DEV Community

Thales Souza
Thales Souza

Posted on

I was tired of AI forgetting my architecture decisions, so I built a transactional context manager for Git

#ai #architecture #git #llm

If you use Cursor, Claude Desktop, or ChatGPT to write software every day, you probably know this exact feeling:

You spend 30 minutes carefully explaining your domain, why you chose a specific library, why you banned another one, and how your database schema is structured.

Twenty prompts later, the LLM hallucinates a dependency you explicitly told it not to use, rewrites a core architecture pattern, or completely forgets an architectural decision you made yesterday.

The problem isn't that current models are dumb. The problem is that LLMs are stateless compute, but we treat them as if they had persistent memory.

Vector databases (RAG) often bring noisy, out-of-context chunks. Copy-pasting massive system_prompt.txt files burns your token budget and gets out of sync with your code in 3 days.

I wanted a deterministic, version-controlled, and safe way to handle this. So I built PactX.

The core philosophy: Git is the source of truth

Instead of relying on AI vendor memory or messy floating markdown files, PactX creates a structured, human-readable directory in your repo: .ai-context/.

Inside, you keep:

  • rules.md — Strict constraints (e.g., "Always use Java 21 records, never use Lombok").
  • state.md — Current milestone and roadmap.
  • decisions/ — Sequential ADRs (DEC-001.md, DEC-002.md).
  • requirements.md — Business requirements tied bidirectionally to ADRs.
  • glossary.md & discarded.md — Domain terms and rejected architectural paths.

All of this lives inside Git alongside your code. When a branch merges, the context merges. When you roll back a commit, your AI context rolls back with it.

How it actually works in a daily workflow

PactX runs as a closed loop with two main commands:

1. Egress: pactx pack

When you start a conversation with any AI, you run:

npx @trsthales/pactx pack
Enter fullscreen mode Exit fullscreen mode

It takes your branch, recent commits, rules, requirements, and decisions, compresses them into a minimal payload (~400 tokens), and copies it straight to your clipboard. You paste it at the start of your chat, and the AI immediately knows the rules and current state.

2. Ingress: pactx update

When the AI proposes a new architectural decision or updates a requirement, you don't edit markdown files manually. You run:

npx @trsthales/pactx update
Enter fullscreen mode Exit fullscreen mode

It accepts an incremental patch from the AI, shows you a full diff for review, and applies it.

Why we built a Write-Ahead Logging (WAL) engine for a CLI

One of the worst things an AI tool can do is corrupt your repo or overwrite files partially if a script crashes halfway through.

To prevent this, PactX doesn't just do fs.writeFileSync. It has an internal Transaction Engine with Write-Ahead Logging (WAL):

  1. Every context change writes a journal entry to .pactx/transactions/ in a PREPARED state.
  2. Changes are written atomically via temp files and native renames.
  3. If your terminal dies or power goes out mid-operation, the next command detects the uncommitted transaction and either rolls it back cleanly or recovers.
  4. Security-wise, everything is jailed to the Git root using fs.realpathSync.native to block symlink attacks and path traversal.

Native Model Context Protocol (MCP) Support

If you use Claude Desktop or Cursor, you don't even need to copy and paste.

PactX includes a native MCP server:

pactx serve --mcp
Enter fullscreen mode Exit fullscreen mode

Once hooked into your claude_desktop_config.json or Cursor settings, the AI can read your project context, check health rules, and propose architectural updates through tools in real-time, while still requiring your confirmation before applying anything to disk.

Try it out (Feedback wanted!)

PactX is 100% open source (MIT), written in TypeScript, and currently has a suite of 140+ unit/integration tests.

You can spin it up in your repo right now:

npx @trsthales/pactx init
Enter fullscreen mode Exit fullscreen mode

Other useful commands:

Feel free to roast the code, open issues, or drop suggestions in the comments. I'd love to hear how you currently manage context drift in your own AI workflows.

Top comments (0)