Metadata-Version: 2.4
Name: threadbase
Version: 0.1.0
Summary: Hooks-based constraint injection for Claude Code — survives compaction
License: MIT
Keywords: claude,claude-code,hooks,constraints,compaction
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Threadbase

**Memory for coding agents that keep forgetting the exact rules of your project.**

Threadbase is a selective memory layer for repeated coding workflows. It stores exact project constraints, implementation rules, and technical facts so later AI runs stop making the same implementation mistakes.

This is **not** broad AI memory.  
This is **not** an AI operating system.  
This is **not** trying to remember everything.

The v0 wedge is narrow on purpose:

**exact technical constraints, rules, and facts in repeated coding workflows.**

---

## The problem

Coding agents are useful for one run, then forget the exact rules of your repo.

You keep re-explaining things like:

- use SQLite, not Postgres
- preserve backward compatibility
- never use this pattern
- these are the valid status values
- this endpoint works this way
- this migration path is the approved one

So the agent drifts:

- suggests the wrong stack
- violates schema constraints
- resurfaces already-rejected approaches
- ignores prior project decisions

After enough runs, it feels like you are starting from zero again.

---

## What Threadbase does

Threadbase stores high-signal project memory outside the normal conversation flow and retrieves it later when the same technical topics come up again.

It is strongest when memory is:

- concrete
- exact
- retrieval-friendly
- written in vocabulary likely to recur later

That means Threadbase works best for:

- **technology-name constraints**  
  `SQLite, not Postgres`

- **operation-name constraints**  
  `schema changes require a migration`

- **endpoint / mechanism facts**  
  `the /memory/retrieve endpoint uses keyword overlap scoring over indexed tokens`

- **named-value facts**  
  `valid run statuses are pending, running, completed, failed`

---

## What Threadbase v0 is good at

Threadbase v0 is strongest for:

- exact project constraints
- implementation rules
- migration / schema boundaries
- concrete technical facts
- repeated coding workflows with stable vocabulary

The best current use case is:

**helping coding agents remember exact project rules across repeated runs.**

---

## What Threadbase v0 is not good at

Threadbase v0 is **not** a general semantic memory engine.

It is weaker for:

- broad direction questions
- abstract paraphrases
- strategic “what should we do next?” prompts
- negative constraints surfaced through broad positive-direction queries

One-line truth:

**Threadbase v0 works where language is concrete and recurring; it breaks where intent is abstract and paraphrased.**

That boundary is real and intentional.

---

## Why the narrow scope matters

Most memory products try to remember everything.

Threadbase is doing the opposite.

The bet is that a smaller trusted memory surface is more useful than a bigger, fuzzier one.

Right now, that means focusing on memory that is:

- binary
- concrete
- easy to verify
- clearly useful in later coding runs

The value is not “more AI.”

The value is:

- less re-explaining
- fewer repeated implementation mistakes
- less technical drift
- more reliable follow-up runs

---

## Example

Without Threadbase:

- Run 1: you tell the agent to use SQLite
- Run 3: it suggests Postgres anyway
- Run 5: it forgets migration constraints
- Run 8: you are repeating the same rules again

With Threadbase:

- the SQLite constraint is stored
- the migration rule is stored
- later runs retrieve the right rule when the same technical topic comes up
- unrelated queries stay clean

The goal is simple:

**run 12 should not forget what run 2 already learned.**

---

## Current product truth

Threadbase v0 has already proven a few things:

- exact-term technical constraints can be retrieved reliably
- exact-term technical facts can be retrieved reliably
- irrelevant out-of-domain retrieval can stay empty
- disciplined memory authoring matters more than endless retriever tuning

The core insight is:

**the discipline is the primitive.**

Threadbase works when memory is written clearly enough for later runs to reuse.

---

## What makes a good memory item

Good memory is:

- specific
- concrete
- reusable
- likely to match future technical queries

Good examples:

- `Threadbase uses SQLite, not Postgres.`
- `Preserve backward compatibility when changing schema.`
- `The /memory/retrieve endpoint uses keyword overlap scoring over indexed tokens.`
- `Valid run statuses are pending, running, completed, failed.`

Bad memory is:

- vague
- advisory
- abstract
- unlikely to recur in similar language

Bad examples:

- `Follow the correct process when setting things up.`
- `Important things to keep in mind.`
- `Threadbase should be reliable and easy for agents.`

---

## Honest limitations

Threadbase v0 does **not** claim to solve:

- semantic retrieval across broad paraphrases
- general strategic memory
- open-ended product-direction guardrails
- memory for everything

If the future query uses very different vocabulary than the stored memory, retrieval gets less reliable.

That is the current boundary.

---

## Who this is for

The best first user is:

**a solo builder or small technical team using coding agents repeatedly on the same codebase**

Especially people using tools like:

- Claude Code
- Cursor
- Copilot
- other agent-style coding workflows

If you are tired of re-explaining the same project rules over and over, this is the problem Threadbase is aimed at.

---

## One-sentence pitch

**Threadbase helps coding agents remember exact project constraints, implementation rules, and technical facts across repeated runs so they stop making the same implementation mistakes.**

---

## Status

Threadbase is still early.

The current v0 wedge is real, but narrow.

That is intentional.

The goal right now is not to sound big.  
The goal is to be useful.

---

## Contact / interest

If this is a pain you have too, that is the thing I want to hear.

Especially if your coding agent keeps forgetting:

- stack constraints
- migration rules
- banned tech choices
- endpoint / schema facts
- prior implementation decisions
