\r \r

HedgehogMemory\r

\r HedgehogMemory gives AI agents infinite persistent memory using a radial compression architecture. Memory is organized as Lines of Nodes — each Node stores the same content at 5 abstraction levels (L0–L4). The L0 one-liner of every node is always loaded at session start (~200 tokens total), so the agent always knows what it knows.\r \r Key guarantee: Memory is NEVER deleted. Old context is only compressed into smaller abstractions. The verbatim original is always recoverable at L4.\r \r

Installation\r

\r

pip install hedgehog-memory\r
pip install "hedgehog-memory[openai]"   # with OpenAI summarizer (recommended)\r
```\r
\r
## Abstraction Levels\r
\r
| Level | Max length | Use case |\r
|-------|-----------|----------|\r
| L0 | 80 chars | One-liner, always in context |\r
| L1 | 200 chars | Navigation preview |\r
| L2 | 600 chars | Detailed summary |\r
| L3 | 1800 chars | Full context summary |\r
| L4 | unlimited | Verbatim original |\r
\r
## Quick Start\r
\r
```python\r
from radial_memory import ContextWindowManager\r
import os\r
\r
mgr = ContextWindowManager(\r
    base_path=os.environ.get("HEDGEHOG_MEMORY_PATH", "./memory_store")\r
)\r
\r
# SESSION START: get ~200-token origin overview (all L0 summaries)\r
overview = mgr.reset()\r
print(overview)  # inject this into your system prompt\r
\r
# LOAD: find relevant past context by query\r
result = mgr.load("Python async patterns")\r
if result.found:\r
    print(result.content)   # L1 summary by default\r
    result = result.drill_deeper()     # go to L2\r
    full = result.load_full_state()    # get verbatim original (L4)\r
\r
# COMMIT: save current session to memory\r
mgr.commit(\r
    topic="Async Python debugging session",\r
    full_context="Complete session transcript goes here...",\r
    tags=["python", "async", "debugging"]\r
)\r
```\r
\r
## With OpenAI Summarizer (recommended for quality)\r
\r
```python\r
from radial_memory import ContextWindowManager\r
from radial_memory.summarizer import OpenAISummarizer\r
import os\r
\r
summarizer = OpenAISummarizer(\r
    api_key=os.environ["OPENAI_API_KEY"],\r
    model="gpt-4o-mini"\r
)\r
mgr = ContextWindowManager(\r
    base_path=os.environ.get("HEDGEHOG_MEMORY_PATH", "./memory_store"),\r
    summarizer=summarizer\r
)\r
```\r
\r
## Agent Workflow Pattern\r
\r
Apply this pattern every session:\r
\r
```python\r
# 1. SESSION START\r
overview = mgr.reset()\r
# overview = all L0 one-liners for every stored node (~200 tokens)\r
# Inject overview into your system prompt / context window\r
\r
# 2. QUERY - find relevant past context\r
result = mgr.load(query=user_request)\r
if result.found:\r
    context = result.content  # L1 summary, ~200 chars\r
    # Need more detail?\r
    result = result.drill_deeper()   # L2, ~600 chars\r
    result = result.drill_deeper()   # L3, ~1800 chars\r
    full = result.load_full_state()  # L4, verbatim original\r
\r
# 3. WORK - perform task with full context available\r
\r
# 4. COMMIT - persist session to memory\r
mgr.commit(\r
    topic="Brief description of this session",\r
    full_context=full_session_log,\r
    tags=["topic1", "topic2"]\r
)\r
```\r
\r
## Status Report\r
\r
```python\r
report = mgr.status_report()\r
# Returns: total lines, total nodes, last commit timestamp\r
print(report)\r
```\r
\r
## Design Principles\r
\r
- **Never deletes** — only compresses. The verbatim original is always recoverable.\r
- **Origin always in context** — L0 summaries of all nodes load at session start (~200 tokens).\r
- **Radial navigation** — query finds the most relevant node by keyword overlap, then drill deeper on demand.\r
- **Pluggable summarizer** — swap OpenAI / LiteLLM / custom backends without changing your workflow code.\r
- **Zero mandatory dependencies** — pure Python stdlib. Works out-of-the-box with KeywordSummarizer.\r
- **Single-file storage** — all memory in one `origin.json`. Atomic writes, no corruption.\r
\r
## Source & Docs\r
\r
- GitHub: https://github.com/vvxer/HedgehogMemory\r
- PyPI: `pip install hedgehog-memory`\r
- Issues: https://github.com/vvxer/HedgehogMemory/issues\r