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

Thales Souza — Thu, 27 Aug 2026 11:38:08 +0000

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

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

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):

Every context change writes a journal entry to .pactx/transactions/ in a PREPARED state.
Changes are written atomically via temp files and native renames.
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.
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

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

Other useful commands:

pactx doctor — Audits your context for broken references or missing ADRs.
pactx status --telemetry — Shows token footprint and context distribution.
pactx rollback — Safely reverts the last applied context change.
GitHub: https://github.com/trsthales/pactx
NPM: https://www.npmjs.com/package/@trsthales/pactx

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.

Tired of having to configure the project every time?

Thales Souza — Sun, 25 Jan 2026 09:10:07 +0000

After spending 1-2 weeks configuring a project before actually starting it, I decided to create a SaaS builder. Initially, it was just CRUD operations, but recently I implemented a text-to-code functionality where the user writes the business logic and the implemented system in natural language. To organize my ideas, I've compiled some articles on a blog: https://blog.thalesouza.com.br/. Tell me, what do you think about this time we spend just configuring projects?

DEV Community: Thales Souza