Pyforge-memory – three-tier memory for AI agents that works
Pyforge-memory is a three-tier memory system for AI agents that reduces context window usage from ~3000 to ~1000 characters using verbatim, keyword, and digest layers, preventing identity prompt truncation.
Notifications You must be signed in to change notification settings
Fork 0
Star 0
BranchesTags
Open more actions menu
Folders and files
NameName
Last commit message
Last commit date
Latest commit
History
2 Commits
2 Commits
.github
.github
pyforge_memory
pyforge_memory
.gitignore
.gitignore
LAUNCH_POST.md
LAUNCH_POST.md
LICENSE
LICENSE
README.md
README.md
index.html
index.html
pyproject.toml
pyproject.toml
Repository files navigation
Three-tier memory for AI agents. Keeps context clean, relevant, and manageable — no more drowning your LLM in 3000+ characters of diary before it can think.
Battle-tested in production at Forged Logic.
What problem does it solve?
Most AI memory tools dump every conversation into the context window. After 50 exchanges, your agent's identity prompt gets silently truncated and it reverts to generic assistant behavior.
pyforge-memory uses three tiers instead:
Tier What it is Budget Behavior
Verbatim Last N exchanges exactly as they happened ~400 chars Keeps the flow
Keyword Memory entries matching keywords in the current message ~300 chars Relevant recall
Digest Compressed rolling summary of older conversations ~300 chars Continuity
Total context drops from ~3000 characters to ~1000 — and every character is the right character.
Features
Three-tier architecture — verbatim recency, keyword relevance, compressed history
Poison filtering — detects and blocks generic assistant-script output before it poisons memory
Configurable — set your own forbidden terms, stop words, memory limits
File-based — JSONL storage, no database, no API keys, runs anywhere
Knowledge directory — keyword-search across text files for domain context
Framework agnostic — works with any LLM API (Ollama, OpenAI, Claude, local)
Install
pip install pyforge-memory
Quick start
from pyforge_memory import MemoryEngine
Initialize with storage paths
engine = MemoryEngine( memory_dir="./my_agent/memory", knowledge_dir="./my_agent/knowledge" )
Your LLM callable (any function that takes messages and returns text)
def llm_call(messages):
... call your LLM here ...
return response
Build context for each user message
messages = engine.build_context( user_message="what did we discuss about the database schema?", system_prompt="You are a helpful coding assistant.", query_fn=llm_call, )
Send to your LLM
response = llm_call(messages)
Save the exchange
engine.save_exchange("what did we discuss about the database schema?", response)
How it works
User message arrives │ ▼ ┌──────────────────┐ │ 1. Extract │ Pull meaningful keywords, strip stop words │ keywords │ └──────┬───────────┘ │ ▼ ┌──────────────────┐ │ 2. Verbatim │ Last N raw exchanges, poison-filtered, │ layer │ near-duplicate detection └──────┬───────────┘ │ ▼ ┌──────────────────┐ │ 3. Keyword │ Search memory + knowledge files │ layer │ for keyword matches, score and rank └──────┬───────────┘ │ ▼ ┌──────────────────┐ │ 4. Digest │ Compressed summary of old conversations │ layer │ auto-generated when memory > 10 entries └──────┬───────────┘ │ ▼ ┌──────────────────┐ │ 5. Assemble │ [system] + verbatim + keyword + digest │ context │ + [user] → ready for LLM └──────────────────┘
Customizing poison detection
engine = MemoryEngine( forbidden_terms=[ "i am an ai assistant", "as a language model",
Add your own patterns
] )
Check any text
if engine.is_poisoned("As an AI assistant, I cannot..."): print("Caught it!")
Knowledge base
Drop text files into your knowledge directory. They're keyword-searched when relevant:
my_agent/knowledge/ ├── database-schema.txt ├── api-docs.txt └── coding-conventions.txt
Why three tiers?
Verbatim alone → loses context from older conversations
Keyword alone → loses the flow of the current conversation
Digest alone → too compressed, misses specifics
Three tiers together: recency + relevance + compression.
License
MIT © The Constellation Forge
Support
If this helped your project, tips are welcome:
GyhqwvFv4ZX3co7T2tziLZTU1vMJoYjfJx2dpG3FPXsc
View on Solana Explorer
About
No description, website, or topics provided.
Resources
Readme
License
MIT license
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
0 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases
No releases published
Packages 0
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
Python 51.8%
HTML 48.2%