parsica-memory 5.2.1

File-based persistent memory for AI agents. Zero dependencies.

🧠 Parsica-Memory

Persistent, intelligent memory for AI agents. Zero dependencies. Pure Python. File-backed.

---

What Is This?

AI agents are stateless by default. Every spawn is a cold start. parsica-memory gives agents a persistent, searchable, intelligent memory store that:

• Remembers across sessions, spawns, and restarts
• Retrieves the right memories using an 11-layer BM25+ search engine
• Decays old memories gracefully so signal stays high
• Learns from mistakes, facts, and procedures with specialized memory types
• Shares knowledge across multi-agent teams
• Enriches itself via LLM hooks to dramatically improve recall
• Cross-session recall — semantic memories surface across all sessions automatically

No vector database. No API keys required. No external services. Just pip install and go.

---

⚡ Quick Start

pip install parsica-memory

from parsica_memory import MemorySystem

mem = MemorySystem(workspace="./memory", agent_name="my-agent")
mem.load()

# Store a memory
mem.ingest("Deployed v2.3.1 to production. All checks green.",
          source="deploy-log", session_id="session-123")

# Search with cross-session recall
results = mem.search("production deployment",
                     session_id="session-456",
                     cross_session_recall="semantic")
for r in results:
    print(r.content)

mem.save()

That's it. No config files needed.

---

📦 Installation

pip install parsica-memory

Version: 1.0.1 Requirements: Python 3.8+ · Zero external dependencies · stdlib only

---

🔑 Key Features

11-Layer Search Engine

Not a simple keyword matcher. Every query runs through:

1. BM25+ TF-IDF — baseline relevance with delta floor
2. Exact Phrase Bonus — verbatim matches score higher
3. Field Boosting — tags, source, category weighted
4. Rarity & Proper Noun Boost — rare terms and names surface
5. Positional Salience — intro/conclusion bias
6. Semantic Expansion — PPMI co-occurrence query widening
7. Intent Reranker — temporal, entity, howto detection
8. Qualifier & Negation — "failed" ≠ "successful"
9. Clustering Boost — coherent result groups score higher
10. Embedding Reranker — local MiniLM embeddings (no API)
11. Pseudo-Relevance Feedback — top results refine the query

Memory Types

Type	Decay Rate	Importance	Use Case
episodic	Normal	1×	General events
semantic	Normal	1×	Facts, decisions — crosses sessions
fact	Normal	High recall	Verified knowledge
mistake	10× slower	2×	Never forget failures
preference	3× slower	1×	User/agent preferences
procedure	3× slower	1×	How-to knowledge

Cross-Session Recall (v1.0.1)

# From session B, find semantic memories stored in session A
results = mem.search(
    "what's the API key format?",
    session_id="session-B",
    cross_session_recall="semantic"  # "all" | "semantic" | "none"
)

• "all" — no filtering (default, backward compatible)
• "semantic" — other sessions' memories only if memory_type == "semantic"
• "none" — strict session isolation

Auto Memory Type Classification

Memories are automatically classified as semantic (facts, decisions, preferences) or episodic (events, tasks, logs) at ingest time. No manual tagging needed.

LLM Enrichment

Pass an enricher callable to dramatically improve recall:

def my_enricher(content: str) -> dict:
    # Call any LLM — returns tags, summary, keywords, search_queries
    return {"tags": [...], "summary": "...", "keywords": [...], "search_queries": [...]}

mem = MemorySystem(workspace="./memory", agent_name="my-agent", enricher=my_enricher)

Enriched fields get boosted weights in search: search_queries 3×, enriched_summary 2×, search_keywords 2×.

Context Packets

Cold-spawn solution for sub-agents:

packet = mem.build_context_packet(
    task="Deploy the auth service",
    max_tokens=3000,
    include_mistakes=True
)
# Inject packet.render() into sub-agent system prompt

Graph Intelligence

Automatic entity extraction and knowledge graph:

path = mem.entity_path("payment-service", "database", max_hops=3)
triples = mem.graph_search(subject="PostgreSQL", relation="used_by")

Tiered Storage

Tier	Age	Behavior
Hot	0–3 days	Always loaded
Warm	3–14 days	Loaded on-demand
Cold	14+ days	Requires include_cold=True

Input Gating

P0–P3 priority classification drops noise before it enters the store:

mem.ingest_with_gating("ok thanks", source="chat")  # → dropped (P3)
mem.ingest_with_gating("Production outage: auth down", source="incident")  # → stored (P0)

Shared / Team Memory

from parsica_memory import AgentRole

pool = mem.enable_shared_pool(
    pool_dir="./shared",
    pool_name="project-alpha",
    agent_id="worker-1",
    role=AgentRole.WRITER
)
mem.shared_write("Research complete: competitor uses GraphQL", namespace="research")

MCP Server

python -m parsica_memory serve --workspace ./memory --agent-name my-agent

Works with Claude Desktop and any MCP-compatible client.

---

🖥️ CLI

# Initialize a workspace
python -m parsica_memory init --workspace ./memory --agent-name my-agent

# Check status
python -m parsica_memory status --workspace ./memory

# Rebuild knowledge graph
python -m parsica_memory rebuild-graph --workspace ./memory

# Start MCP server
python -m parsica_memory serve --workspace ./memory --agent-name my-agent

---

🔧 Core API

from parsica_memory import MemorySystem

mem = MemorySystem(
    workspace="./memory",          # Required
    agent_name="my-agent",         # Required — scopes the store
    half_life=7.0,                 # Decay half-life in days
    enricher=None,                 # LLM enrichment callable
    tiered_storage=True,           # Hot/warm/cold tiers
    graph_intelligence=True,       # Entity extraction + graph
    semantic_expansion=True,       # PPMI query expansion
)

# Lifecycle
mem.load()                         # Load from disk
mem.save()                         # Save to disk
mem.flush()                        # WAL → shards
mem.close()                        # Flush + release

# Ingestion
mem.ingest(content, source=..., session_id=..., channel_id=...)
mem.ingest_fact(content, source=...)
mem.ingest_mistake(what_happened=..., correction=..., root_cause=..., severity=...)
mem.ingest_preference(content, source=...)
mem.ingest_procedure(content, source=...)
mem.ingest_file(path, category=...)
mem.ingest_url(url, depth=2)

# Search
mem.search(query, limit=10, cross_session_recall="semantic")
mem.search_with_context(query, cooccurrence_boost=True)
mem.recent(limit=20)

# Graph
mem.graph_search(subject=..., relation=..., obj=...)
mem.entity_path(source, target, max_hops=3)

# Context
mem.build_context_packet(task=..., max_tokens=3000, include_mistakes=True)

# Maintenance
mem.compact()
mem.consolidate()
mem.reindex()
mem.forget(topic=..., before_date=...)

---

🏗️ Architecture

parsica-memory/
├── Core: MemorySystem, MemoryEntry, WAL
├── Storage: ShardManager, TierManager, GCS backend
├── Search: 11-layer BM25+ pipeline
├── Intelligence: EntityExtractor, MemoryGraph, LLM Enricher
├── Multi-Agent: SharedMemoryPool, AgentRoles
├── Context: ContextPacketBuilder
└── Server: MCP server, CLI

---

Relationship to Antaris-Memory

parsica-memory and antaris-memory share the same core engine. They are functionally identical — same 11-layer search, same memory types, same API. The difference is branding:

• antaris-memory — part of the antaris-suite ecosystem
• parsica-memory — standalone package, same features, independent identity

Use whichever fits your project. They're interchangeable.

---

📄 License

Apache 2.0

---

🔗 Links

• PyPI: https://pypi.org/project/parsica-memory/
• GitHub: https://github.com/Antaris-Analytics-LLC/Parsica-Memory
• Antaris Analytics: https://antarisanalytics.ai

---

Built by Antaris Analytics LLC for production AI agent deployments.