Metadata-Version: 2.4
Name: shiro-memory
Version: 4.9.3
Summary: Persistent memory for Shiro — upgraded to antaris-memory v5.0.1 feature parity. Stripped: MCP, Supabase collection, sharding.
Author-email: Antaris Analytics <dev@antarisanalytics.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Antaris-Analytics-LLC/shiro-memory
Project-URL: Repository, https://github.com/Antaris-Analytics-LLC/shiro-memory
Keywords: ai,memory,agents,llm,persistence,recall
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: embeddings
Requires-Dist: openai>=1.0; extra == "embeddings"
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.0; extra == "semantic"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Provides-Extra: pro
Requires-Dist: openai>=1.0; extra == "pro"
Requires-Dist: sentence-transformers>=2.0; extra == "pro"
Dynamic: license-file

# shiro-memory

Persistent memory for AI agents. Shiro's personal memory library — forked from [antaris-memory](https://github.com/Antaris-Analytics-LLC/antaris-suite), upgraded to v5.0.1 feature parity, with sharding/MCP/Supabase stripped per spec.

[![PyPI](https://img.shields.io/pypi/v/shiro-memory)](https://pypi.org/project/shiro-memory/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-green.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-orange.svg)](LICENSE)

## Install

```bash
pip install shiro-memory==4.9.2
```

Zero dependencies. No API keys. No external services.

## What's stripped (intentional)

| Feature | Status | Reason |
|---|---|---|
| Sharding | ❌ Removed | Not needed at Shiro's scale; `use_sharding` accepted but ignored |
| MCP server | ❌ Removed | OpenClaw handles the agent interface |
| Supabase collection | ❌ Removed | No cloud sync |

Everything else from antaris-memory 5.0.1 is present.

## Quick Start

```python
from antaris_memory import MemorySystem

mem = MemorySystem(
    workspace="~/.openclaw/shiro-store/shared",
    agent_name="shiro-shared",   # REQUIRED — prevents memory bleed between agents
    half_life=30,                # 30-day decay (longer than default 7)
)
mem.load()

mem.ingest("My favorite color is cobalt blue", source="conversation")

results = mem.search("favorite color")
for r in results:
    print(r.entry.content)

mem.save()
```

**`agent_name` is required.** Without it, a `UserWarning` is raised and memories from different agents blend together with no way to separate them.

## LLM Enrichment (highest-leverage feature)

Wire up any LLM to dramatically improve recall on vocabulary-gap queries:

```python
import anthropic, json

client = anthropic.Anthropic()

def enricher(content: str) -> dict:
    resp = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=300,
        messages=[{"role": "user", "content": f"""Return JSON only:
{{"tags": ["tag1"], "summary": "search-optimized restatement",
 "keywords": ["kw1"], "search_queries": ["natural query that should find this"]}}
Content: {content[:400]}"""}]
    )
    try:
        return json.loads(resp.content[0].text)
    except Exception:
        return {}

mem = MemorySystem(
    workspace="~/.openclaw/shiro-store/shared",
    agent_name="shiro-shared",
    enricher=enricher,
)
```

Without enrichment: BM25 on raw content only. With enrichment: query-document pairs at ingest time, 3× TF weight on `search_queries`, 2× on `enriched_summary` and `keywords`. This is what closes the vocabulary gap ("What state do I live in?" finding "I live in California").

## Memory Types

```python
# Mistakes decay 10× slower and score 2× higher — they stick around
mem.ingest_mistake(
    what_happened="Used DROP TABLE instead of TRUNCATE",
    correction="Always use TRUNCATE for clearing data",
    root_cause="Confused SQL semantics under pressure",
    severity="high",
)

# Facts — verified knowledge
mem.ingest_fact("Production DB is PostgreSQL 14.2 on RDS us-east-1", source="infra-docs")

# Preferences — persist 3× longer
mem.ingest_preference("Prefers concise responses under 200 words", source="feedback")

# Procedures — task-matched recall
mem.ingest_procedure("Deployment: test → tag → staging → monitor 10min → prod", source="runbook")
```

## Search

```python
# 11-layer search pipeline
results = mem.search(
    "production deployment failure",
    limit=10,
    memory_type="mistake",     # filter by type
    explain=True,              # include score breakdown
)

# Search with co-occurrence expansion
results, ctx = mem.search_with_context(
    "API problems",
    cooccurrence_boost=True,
)
print(f"Expanded: {ctx.expanded_query}")
```

## Context Packets (cold-spawn solver)

```python
packet = mem.build_context_packet(
    task="Deploy auth service to production",
    tags=["deployment", "auth"],
    max_tokens=1200,
    include_mistakes=True,
)
print(packet.render())  # inject into agent system prompt
```

## Stats & Health

```python
stats = mem.get_stats()
print(f"Entries: {stats['total_entries']}")
print(f"Hot/Warm/Cold: {stats['hot_entries']}/{stats['warm_entries']}/{stats['cold_entries']}")
print(f"Enriched: {stats['enriched_entries']}")
print(f"Graph nodes: {stats['graph_nodes']}")

health = mem.get_health()
print(health["status"])  # "ok" or "degraded"
```

## OpenClaw Plugin

The OpenClaw plugin is in `openclaw-plugin/index.js`. See [PLUGIN_SPEC.md](PLUGIN_SPEC.md) for architecture details.

**v2.1.1 install:**
```bash
# 1. Install library
pip install shiro-memory==4.9.2

# 2. Copy plugin
cp openclaw-plugin/index.js ~/.openclaw/extensions/shiro-memory/index.js

# 3. Wipe old namespace data (clean start)
rm -rf ~/.openclaw/shiro-store/namespaces/

# 4. Restart OpenClaw
```

**Store layout (v2.1.x):**
```
~/.openclaw/shiro-store/
├── private/    ← shiro-private (Jason's sessions only)
└── shared/     ← shiro-shared (all sessions)
```

## Version History

| Version | Date | Notes |
|---|---|---|
| **4.9.2** | 2026-03-10 | Fix `MemoryEntry.__slots__` missing `agent_id`/`channel_id` |
| 4.9.1 | 2026-03-10 | Fix search.py (v1 engine → 11-layer); Plugin v2.1.1 temp-file fix |
| 4.9.0 | 2026-03-10 | Full v5.0.1 feature parity upgrade; Plugin v2.1.0 |
| 4.1.0 | 2026-02-26 | Original fork baseline |

## License

Apache 2.0 — see [LICENSE](LICENSE)

---

*shiro-memory is maintained by [Antaris Analytics LLC](https://antarisanalytics.ai). Based on [antaris-memory](https://github.com/Antaris-Analytics-LLC/antaris-suite).*
