SMEHA Memory

SMEHA Memory is a local-first memory engine for software agents. It helps an agent carry useful context across restarts, retrieve relevant facts before a step, record what actually worked or failed, and surface contradictory evidence before repeating a mistake.

The package is dependency-free, inspectable, and safe to run offline. It ships code and schemas only: no private database, logs, credentials, or project-specific memory dump.

What It Provides

• Durable local memory through an append-only JSONL log and deterministic replay.
• Relevant recall with typed nodes, tags, metadata, and weighted relations.
• Outcome-aware context through observer traces and success/failure receipts.
• Explicit contradiction reporting before the next agent step.
• A deterministic hashing embedder, so examples work without an API key.
• A Python API and CLI with no runtime dependencies.

How It Works

SMEHA Memory keeps two layers:

• an in-memory graph of nodes and weighted typed edges for fast recall
• an append-only JSONL event log that can replay the graph exactly

The default embedder is a deterministic hashing embedder. That keeps the package offline, reproducible, and key-free. If you need stronger semantic recall, pass your own embedder object with an embed(text) -> tuple[float, ...] method.

Install

From a checkout:

pip install -e .

Or use it directly by setting PYTHONPATH=src.

Quick Start

pip install -e .
python -m smeha_memory learn --db local_memory.jsonl "Durable facts belong in the append-only floor."
python -m smeha_memory recall --db local_memory.jsonl "durable facts"
python -m smeha_memory status --db local_memory.jsonl

The local_memory.jsonl file is your private memory log. Do not commit it unless you intentionally want to publish its contents.

Python Usage

from smeha_memory import SmehaMemory

memory = SmehaMemory.open("local_memory.jsonl")

alpha = memory.learn(
    "The renderer should only publish frames after assets are available.",
    kind="engineering_note",
    tags=("rendering", "assets"),
)

beta = memory.learn(
    "Missing dependencies should produce placeholders or block visibility.",
    kind="engineering_note",
    tags=("assets", "dependency"),
)

memory.relate(alpha, beta, relation="supports", weight=0.8)

for hit in memory.recall("asset visibility dependency", k=3):
    print(round(hit.score, 3), hit.node.text)

Outcome-Aware Context

Basic recall answers "what looks relevant?" Outcome-aware context also answers "what warning did we record?" and "did the previous attempt actually land?" These records are ordinary typed nodes in the same append-only log, so they survive replay and can change the context assembled for the next step.

from smeha_memory import SmehaMemory, build_active_context, record_observer_trace, record_outcome

memory = SmehaMemory.open("local_memory.jsonl")
record_observer_trace(
    memory,
    target="demo",
    observer="reviewer",
    signal="verify",
    summary="The browser path must agree with backend state before release.",
)
record_outcome(
    memory,
    target="demo",
    status="split",
    summary="The unit path passed; live browser evidence is still missing.",
)
context = build_active_context(memory, "demo release")

See docs/OUTCOME_AWARE_CONTEXT.md for the record contract and replay ruler.

Temporal Facts And Multi-Hop Recall

AgentMemoryEngine wraps SmehaMemory and adds two capabilities that flat similarity recall does not represent by itself.

Temporal validity. Facts change. current(subject, predicate) returns the latest value; a plain similarity index can return both stale and new mentions and leave the agent to guess which is current.

from smeha_memory import AgentMemoryEngine

eng = AgentMemoryEngine()
eng.remember_fact("project", "uses_storage", "Redis")
eng.remember_fact("project", "uses_storage", "SQLite")   # the fact changed
eng.current("project", "uses_storage")                   # "SQLite"

Multi-hop connectivity. Some answers are connected to the query but not textually similar to it. recall_connected grounds the query to seed nodes, then traverses typed edges.

eng.remember_fact("Alice", "teammate", "Bob")
eng.remember_fact("Bob", "owns", "Redis cluster")

eng.recall("Alice teammate", k=3)                        # flat similarity
eng.recall_connected("Alice teammate", hops=2)           # reaches the two-hop fact

This is where graph memory adds value beyond flat similarity: relations can compose across more than one hop. See tests/test_engine.py for the fail-under-broken comparison.

Extraction is optional. observe(text) can extract (subject, predicate, object) facts through a locally running Ollama model and record each with temporal validity. Explicit remember_fact calls and every other package feature work without Ollama.

To use extraction, pass the local service URL as host=... or set SMEHA_OLLAMA_BASE_URL. The package does not assume a local endpoint or start a model on your behalf.

How It Differs From Common Memory Patterns

SMEHA is a small composable component, not a claim that one memory mechanism fits every agent. The useful distinction is what it preserves for the next step.

Pattern	What it is good at	What SMEHA adds	What SMEHA does not replace
Conversation history	Preserving a chronological exchange	Durable typed records, targeted recall, and outcomes that survive outside one chat window	A chat transcript, messaging UI, or full conversation archive
Vector store / RAG	Finding text that is semantically similar to a query	Typed relations, multi-hop traversal, current-versus-superseded facts, and outcome receipts	Document ingestion, high-scale ANN search, or a stronger embedding model
Knowledge graph	Querying a carefully modeled domain ontology	A lightweight local graph paired with recall and an append-only replay trail	A governed enterprise ontology, schema registry, or symbolic reasoner
Event log / audit trail	Recording immutable changes in order	Retrieval-ready nodes, relations, and evidence-aware context built over an append-only log	A transaction database, multi-writer event platform, or compliance system
Full agent-memory platform	Hosting sessions, policies, tools, and remote services	A dependency-free embeddable memory core that an agent can call locally	Authentication, orchestration, model hosting, or a hosted control plane

Choose SMEHA when an agent needs to remember not only a relevant note, but whether a fact is still current, how it connects to another fact, and whether a previous action actually worked. Pair it with a vector index for stronger semantic retrieval, a source-of-truth database for authoritative state, and an external verifier for claims that need real-world proof.

Agent Usage Pattern

Use it as a small durable memory layer around an agent:

1. Call recall(query) before a non-trivial step to retrieve local context.
2. Do the work against the real source of truth: files, tests, logs, or tools.
3. Call learn(text, tags=...) after a material result, decision, or failure.
4. Use relate(source, target, relation=...) when two records should reinforce each other on future recalls.

Keep private memory files out of git. The library stores user-provided text in plain JSONL by design so that the log is inspectable and easy to back up.

CLI Usage

Learn:

python -m smeha_memory learn --db local_memory.jsonl --kind note --tag assets "Assets must load before visibility."

Recall:

python -m smeha_memory recall --db local_memory.jsonl "asset visibility" --k 5

Status:

python -m smeha_memory status --db local_memory.jsonl

Record a warning and its verified outcome:

python -m smeha_memory observer-trace --db local_memory.jsonl demo \
  "The browser state must agree with backend state." --signal verify
python -m smeha_memory outcome --db local_memory.jsonl demo \
  "The unit path passed; live evidence is still missing." --status split
python -m smeha_memory build-context --db local_memory.jsonl "demo release"

Relate two records:

python -m smeha_memory relate --db local_memory.jsonl SOURCE_ID TARGET_ID --relation supports --weight 0.8

MCP / Agent Integration

This repository intentionally ships no private MCP configuration. To integrate it with an agent runtime, wrap SmehaMemory.open(path) behind your local tooling and expose the operations you need:

• learn(text, kind=None, tags=[])
• recall(query, k=8, tags=[])
• record_observer_trace(target, observer, signal, summary, evidence=[])
• record_outcome(target, status, summary, evidence=[])
• build_active_context(query, k=8)
• status()

Keep the JSONL file local unless you explicitly choose to share it.

Privacy And Safety

• The package ships code only: no private database, exported graph, chat log, or runtime configuration.
• The default embedder is local and deterministic, so examples do not call any external API.
• Memory text is stored in plain JSONL for auditability. Put the JSONL file in a private path, back it up deliberately, and keep it out of git by default.
• If you add an MCP wrapper or stronger embedder, keep credentials in your own secret store, not in this repository.

Tests

From a checkout without installing:

PYTHONPATH=src python -m unittest discover -s tests -v

On Windows PowerShell:

$env:PYTHONPATH = "src"; python -m unittest discover -s tests -v

Scope

This package is a small memory component, not a model runtime or a substitute for external verification. Its default embedder favors portability and reproducibility over semantic quality; production adapters can inject a stronger embedder without changing the persistence or outcome-record APIs.

License

The current version is licensed under the GNU Affero General Public License v3.0 or later. If you modify SMEHA Memory and make that modified version available to users over a network, the AGPL requires you to offer those users the corresponding source code.

Versions previously published under Apache-2.0 remain available under the license terms that accompanied those versions.