Agent Memory

Owner-aware project continuity for agents. Keep project truth, durable decisions, and an explicit owner operating profile available across sessions and models, with evidence links, lifecycle controls, and review before inferred information becomes canonical.

Overview

Agent Memory enables your AI agents to persist useful information across sessions. It is not a generic store for complete conversation history. Snipara keeps compact, reviewed facts, decisions, preferences, and operating constraints at the correct owner scope so future agents inherit approved project context instead of replaying every chat or rediscovering it.

The strongest coding-agent setups use both layers together: execution memory keeps the agent aligned with its workflow state and recent runtime trace, while reviewed memory prevents it from reopening settled engineering decisions.

When an agent needs that operational layer in one hosted fetch, use snipara_resume_context. It packages execution-memory with latest handoff, What Changed, active decisions, and an optional task-scoped work brief instead of exposing execution-memory alone.

Owner-aware project continuity

The durable bootstrap starts from two explicit profile layers. The newest active project/client profile is reserved as the project anchor; additional tenant profiles can still appear as ordinary critical memory when budget allows. A personal owner operating profile describes how the authenticated owner wants agents to communicate, decide, verify, and collaborate. These profiles complement reviewed decisions; they do not replace source documents or become a hidden personality model.

Update the owner profile explicitly

snipara_owner_profile_update(
    profile={
        "preferred_language": "French",
        "communication_style": "Direct, concise, evidence-first",
        "decision_style": "Show tradeoffs, then recommend one path",
        "autonomy_preference": "Execute agreed work end to end",
        "risk_tolerance": "Conservative for production and data",
        "evidence_preferences": "Tests plus live production proof",
        "product_principles": ["Ship only what the product can prove"],
        "non_negotiables": ["Never store secrets in memory"],
        "working_preferences": ["Commit substantial phases separately"]
    },
    evidence_refs=["decision-receipt-123"]
)

Updates patch only the supplied fields by default. Pass replace=true when the supplied object should replace the canonical profile. Integrator client keys also pass a stable external_user_id, which is mapped to an isolated end-user owner.

At session start, snipara_session_memories applies deterministic precedence: project profile → owner profile → active decisions → other durable memory → daily carryover. The project slot uses the newest active project/client profile, while additional tenant profiles can use the remaining critical budget. Profile content is bounded by the bootstrap token budgets and protected from generic compaction rules, so an old but active owner profile is not dropped merely because newer daily notes exist.

Mem0 vs Snipara

If you only need personal or per-agent memory, Mem0 is the closer comparison. Snipara can also store agent and user-scoped memory, but its differentiator for coding teams is governed project, team, and repo memory with evidence, review, invalidation, and lifecycle control.

In short: Mem0 is usually where you keep what one agent or user should remember. Snipara combines an explicit owner profile with the governed truth the project should keep teaching every future agent.

GitHub to Durable Recall

Coding-agent memory should not jump straight from a pull request to a permanent recall. Snipara treats GitHub as evidence first, then promotes selected repo truth into durable memory only after governance and lifecycle checks.

Memory Scope Policy

Choose the narrowest durable owner before writing memory. Raw specs, RFPs, diagrams, and client files stay in context; memory stores compact decisions, preferences, learnings, and reusable state.

Snipara stores agent memory on the reviewed memory model by default. Agent, project, team, and user scopes are owner boundaries, not labels: agent memories require an agent identifier, user memories stay personal to one authenticated or integrator-mapped user, team memories stay with the team, and project memories stay with the active project.

Key Features

• Semantic Storage — Memories are embedded for similarity search
• Source-Linked Evidence — Attach docs, chunks, PRs, issues, and URLs to critical memories
• Lifecycle Controls — Invalidate or supersede stale memories through hosted MCP or companion without losing history
• Verification — Re-check whether a memory is still backed by valid evidence
• Review Queue — Route automated memory writes to an inbox before recall
• Transcript Import API — Preview and bootstrap durable memory from transcripts or notes
• Automation-Safe Capture — Use novelty checks and task commits instead of raw note dumping
• Confidence Decay — Memories lose relevance over time unless reinforced
• Type Classification — Categorize as facts, preferences, decisions, etc.
• TTL Support — Set expiration times for temporary memories
• Metadata Filtering — Filter recalls by type, category, or custom tags

Capture & Review Flow

Not every memory should become durable immediately. Snipara supports a reviewable workflow so teams can automate capture without polluting future recalls.

The authenticated web endpoint POST /api/agents/memory/import previews durable candidates from a session transcript or retrospective and imports them into the review inbox. Use scope: "PROJECT" (the default) for shared project memory or scope: "USER" for memory owned by the authenticated user.

For local human resolution, use snipara-companion Decision Requests: workflow decisions lists pending questions, workflow decide records the reviewer receipt, and memory reviews --emit-decisions turns hosted memory review candidates into the same review channel.

GitHub Evidence Memory

GitHub can become memory only through a governed path. Snipara first treats repository artifacts as evidence: issues, pull requests, review comments, commits, Actions summaries, and linked files keep their GitHub URLs, SHAs, paths, and line numbers where available.

The next layer proposes selected evidence as memory candidates. Those candidates keep source links, risk flags, confidence, and suggested TTLs. They are not durable recall material until policy or a reviewer approves them.

Before and After: one sourced memory prevents the wrong edit

The value is not abstract. A reviewed memory can stop an agent from repeating a stale repo assumption before it edits the wrong file or reopens a closed decision.

MCP Tools

snipara_remember

Store a new memory with optional metadata.

snipara_remember({

  text: "User prefers dark mode in all applications",

  type: "preference",

  category: "ui",

  scope: "project",

  // Omit ttl_days when no automatic expiry is needed

})

Parameters

snipara_remember_if_novel

Store a memory only if it is sufficiently different from existing memories. This is the safest write path for automation and commit hooks.

snipara_remember_if_novel({

  text: "Use Vaultbrix SSH before rolling out Prisma-backed backend releases",

  type: "decision",

  category: "deploy",

  novelty_threshold: 0.92

})

Typical use: commit hooks, session summaries, and workflow automations that should skip near-duplicate memories.

snipara_remember_bulk

Store multiple memories in a single call for efficient batch operations.

snipara_remember_bulk({

  memories: [

    { text: "User prefers TypeScript", type: "preference" },

    { text: "API uses JWT auth", type: "fact", category: "auth" },

    { text: "Deploy to staging first", type: "decision", ttl_days: 30 }

  ]

})

Parameters

Response

{

  "created": 3,

  "failed": 0,

  "memory_ids": ["mem_abc", "mem_def", "mem_ghi"],

  "failures": null,

  "message": "Stored 3 memories successfully"

}

snipara_end_of_task_commit

Persist durable outcomes from a task. Prefer the structured why block when the decision and its rationale are available; summary remains the heuristic fallback for older clients and unstructured handoffs.

snipara_end_of_task_commit({

  task: "Harden webhook delivery",

  why: {

    decision: "Use the durable queue for webhook delivery.",

    rationale: "Deploys can interrupt synchronous delivery.",

    alternatives: ["Synchronous delivery"],

    constraints: ["At-least-once delivery"],

    observed_outcome: "Retries now survive deploys."

  },

  outcome: "completed",

  files_touched: ["apps/web/src/lib/webhooks.ts"]

})

A structured block becomes one atomic PENDING memory and, when it contains a decision, one ProjectDecision DRAFT. It requires a resolved human owner and is never split by summary heuristics. Use dry_run: true to preview it without writing. Unknown top-level or nested parameters are rejected before any write.

Summary-based task commits use project scope by default. With an integrator client key, provide external_user_id to store the extracted memories in that isolated end-user namespace. Structured Why Capture remains project-governed and uses that resolved identity as its human owner; this tool intentionally has no separate scope argument.

snipara_recall

Retrieve memories relevant to a query using semantic search.

Use snipara_recall for durable decisions, learnings, preferences, and carryover. Do not use it as a substitute for source documents. For specs, PDFs, client files, and shared playbooks, start with Project Intelligence Inputs and use snipara_context_query or snipara_shared_context.

On projects where Outcome Loop recall reranking is enabled, recall may include an outcome_loop_rerank block and per-memory outcome_evidence. That ranking signal is based on sample-aware OutcomeStats posterior evidence, not raw Memory.evidenceScore. It is a gated memory recall treatment. Context/chunk retrieval uses a separate opt-in outcome rerank path backed by persisted OutcomeEvidenceStats for chunk targets, live fallback for missing stats, bounded boost-only movement, and a top-relevance exploration floor.

snipara_recall({

  query: "What are the user's UI preferences?",

  limit: 5,

  type: "preference",

  min_relevance: 0.5

})

Parameters

Response

{

  "memories": [

    {

      "memory_id": "mem_abc123",

      "content": "User prefers dark mode in all applications",

      "type": "preference",

      "category": "ui",

      "confidence": 0.92,

      "relevance": 0.87,

      "created_at": "2025-01-20T10:30:00Z",

      "last_accessed_at": "2025-01-23T14:15:00Z",

      "access_count": 0,

      "status": "active",

      "review_status": "approved"

    }

  ],

  "warnings": [],

  "total_searched": 24,

  "query": "What are the user's UI preferences?",

  "timing_ms": 42

}

Confidence values in recall responses are ranking and lifecycle signals, not calibrated advisor-grade probability claims.

snipara_memories

List all memories with optional filters (no semantic search).

snipara_memories({

  type: "decision",

  limit: 20,

  offset: 0

})

snipara_forget

Delete specific memories by ID or filter.

// Delete by ID

snipara_forget({ memory_id: "mem_abc123" })

// Delete all memories of a type

snipara_forget({ type: "todo" })

Memory Lifecycle Tools

Use reviewed memory lifecycle tools when you need memory that can be traced back to evidence and updated safely over time instead of being hard-deleted.

snipara_memory_attach_source

Attach evidence to a memory, such as a document chunk, PR, issue, commit, or URL.

snipara_memory_attach_source({

  memory_id: "mem_abc123",

  evidence_type: "CHUNK",

  chunk_id: "chunk_456",

  snippet: "OAuth callback validates state before token exchange",

  weight: 1.0

})

Use this for fact, decision, and learning memories that should stay grounded in project evidence.

snipara_get_chunk

Retrieve the full content for a referenced chunk when you need to inspect the exact source behind a memory or a query result.

snipara_get_chunk({

  chunk_id: "chunk_456"

})

snipara_memory_verify

Verify whether a memory still has valid supporting evidence.

snipara_memory_verify({

  memory_id: "mem_abc123",

  mark_stale_if_missing: true

})

{

  "memory_id": "mem_v2_abc123",

  "verified": true,

  "total_evidence": 2,

  "valid_evidence": 2,

  "invalid_evidence": 0,

  "evidence_score": 1.0,

  "status": "ACTIVE"

}

snipara_memory_invalidate

Mark a memory as invalid when it is no longer true. This preserves the audit trail better than deleting it outright.

snipara_memory_invalidate({

  memory_id: "mem_abc123",

  invalidated_at: "2026-04-10T14:30:00Z",

  reason: "Legacy OAuth flow replaced by PKCE-only flow"

})

snipara_memory_supersede

Replace an outdated memory with a newer one while keeping the relationship explicit.

snipara_memory_supersede({

  old_memory_id: "mem_old_auth",

  new_memory_id: "mem_new_auth",

  reason: "Authorization server configuration changed"

})

From a terminal workflow, the companion equivalents are snipara-companion memory invalidate <memory-id> and snipara-companion memory supersede <old-memory-id> <new-memory-id>. These commands call the hosted lifecycle tools and keep mutation separate from read-only hygiene commands such as memory audit and memory compact.

Memory Hygiene Tools

Memory hygiene tools help teams review active memory quality without deleting useful history. Use them before and after cleanup workflows, especially when automation writes memories on behalf of agents.

snipara_memory_health

Inspect active memory counts, top categories, compaction settings, and known hygiene anomalies. This tool is read-only.

snipara_memory_health({

  sample_limit: 5

})

Hygiene reasons include document upload receipts, trivial decomposition receipts, execution-plan receipts, and active categories that still contain :superseded.

snipara_memory_clean_candidates

Return a bounded review packet for cleanup. It groups candidates into noise, possible stale rows, duplicate groups, category anomalies, and memories that need human review.

snipara_memory_clean_candidates({

  limit_per_bucket: 10

})

This tool does not mutate memory. Follow up with snipara_memory_invalidate, snipara_memory_supersede, or snipara_memory_compact after reviewing the candidates.

snipara_memory_duplicate_candidates

Return duplicate and supersession candidates only, for workflows that do not need the full hygiene review packet.

snipara_memory_duplicate_candidates({

  limit: 20

})

Decision Log Tools

Use decision tools when a memory is not enough and you need a structured, ADR-style record with rationale, alternatives, and a supersession chain.

snipara_decision_create

Create a formal technical or architectural decision record.

snipara_decision_create({

  title: "Use Redis for background job deduplication",

  owner: "platform-team",

  scope: "backend",

  impact: "HIGH",

  context: "Workers need a shared dedupe layer across deploys",

  decision: "Adopt Redis SETNX-based deduplication",

  rationale: "Faster operational rollout than queue-layer rewrite",

  alternatives: ["Postgres advisory locks", "Kafka compaction"],

  tags: ["jobs", "reliability", "redis"]

})

snipara_decision_query

Search decisions by free text, scope, impact, status, or tags.

snipara_decision_query({

  query: "redis deduplication",

  scope: "backend",

  impact: "HIGH",

  include_superseded: false,

  limit: 10

})

snipara_decision_supersede

Replace an existing decision with a new one while preserving the evolution chain between both records.

snipara_decision_supersede({

  old_decision_id: "DEC-014",

  title: "Move job deduplication to queue middleware",

  owner: "platform-team",

  scope: "backend",

  impact: "HIGH",

  context: "Redis hot key pressure increased with traffic growth",

  decision: "Shift deduplication into queue middleware",

  rationale: "Reduces operational hotspots and centralizes policy"

})

Confidence Decay

Memories naturally lose confidence over time unless they are accessed or reinforced. This prevents stale information from dominating recalls.

Confidence Decay Formula

new_confidence = base_confidence * (0.99 ^ days_since_reference)

Example: 0.9 confidence, 1% daily decay, 7 days

0.9 * (0.99 ^ 7) = 0.84

Reinforcement

A successful snipara_recallupdates the memory's last-access timestamp, so subsequent decay is measured from that reference. Writing the same content is not a reinforcement operation: snipara_remember_if_novel may skip it as a duplicate or return reconciliation guidance.

Memory Types

Best Practices

Guidelines

• Be specific— "User prefers tabs over spaces" not "User has code style preferences"
• Use appropriate types — Helps with filtering and organization
• Set TTL for temporary info — Prevent memory bloat
• Attach evidence for critical memories — Facts and decisions should be verifiable
• Invalidate or supersede stale knowledge — Keep history instead of deleting everything
• Let confidence decay work— Don't manually set confidence to 1.0
• Use duplicate-aware writes — Prefer snipara_remember_if_novelwhen automation should skip duplicates or request reconciliation

Current Packaging

Next Steps