PersistentMind

Persistent, searchable, context-aware memory for AI agents. Store what matters. Never lose context again.

Free and open-source (MIT License) • Zero dependencies • Works locally • No API keys required

---

Why This Skill?

AI agents forget everything between sessions. Every time you start a new conversation, you repeat the same context: your preferences, your project setup, corrections to previous mistakes, procedures you've documented. This skill solves that permanently.

Problems it solves:

• Agents forget user preferences between sessions
• Same mistakes repeated because corrections aren't persisted
• Project context has to be re-explained every time
• No way to build up a team knowledge base over time

---

Core Concepts

Memory Types

Memory Scopes

---

Features

1. Store Memories

from persistentmind import PersistentMind, MemoryType, MemoryScope

mm = PersistentMind(project="my-app")

# Critical correction — will always surface first in context
mm.remember(
    "Never use wildcard imports — the linter will fail CI",
    memory_type=MemoryType.CORRECTION,
    scope=MemoryScope.PROJECT,
    importance=10.0,
    tags=["linting", "ci", "imports"]
)

# Global preference — applies everywhere
mm.remember(
    "User prefers code examples over long explanations",
    memory_type=MemoryType.PREFERENCE,
    scope=MemoryScope.GLOBAL,
    importance=8.0
)

# Auto-tags extracted from content automatically if you don't specify
mm.remember(
    "The Stripe API key is in .env as STRIPE_SECRET_KEY",
    memory_type=MemoryType.FACT,
    scope=MemoryScope.PROJECT,
    importance=9.0
)

2. Search Memories

# Full-text search with relevance scoring
results = mm.recall("database migrations")
for r in results:
    print(f"[{r.relevance_score:.2f}] [{r.memory.memory_type}] {r.memory.content}")

# Search with filters
results = mm.recall("imports", type_filter="correction", min_importance=7.0)

# Get by type
corrections = mm.recall_by_type(MemoryType.CORRECTION)

# Get by tag
db_memories = mm.recall_by_tag("database")

3. Inject Context Into Prompts

# Get a formatted context block to prepend to any prompt
context = mm.get_context(project="my-app", max_tokens_estimate=1500)

prompt = f"""
{context}

---

User request: {user_input}
"""

Output:

# Relevant Memory Context

⚠️ [CORRECTION] Never use wildcard imports — the linter will fail CI
⚙️ [PREFERENCE] User prefers code examples over long explanations
📌 [FACT] The Stripe API key is in .env as STRIPE_SECRET_KEY
📋 [PROCEDURE] Run migrations with: poetry run alembic upgrade head

Corrections always surface first. Importance score determines ranking.

4. Memory Management

# Update an existing memory
mm.update_memory(memory_id="mem_abc123", importance=9.0, tags=["critical"])

# Archive a memory (soft delete)
mm.forget("mem_abc123")

# Permanently delete
mm.forget("mem_abc123", permanent=True)

# Expire automatically after N days
mm.remember("Temp token: abc...", expires_in_days=7)

5. Deduplication

# Find near-duplicate memories (dry run — just report)
groups = mm.consolidate(dry_run=True)
for g in groups:
    print(f"Found {g['count']} similar memories:")
    for m in g['memories']:
        print(f"  - {m['content']}")

# Actually merge them
mm.consolidate(dry_run=False)

6. Team Sharing

# Export your memory set
mm.export_memories("team_memories.json")

# Import a colleague's memories
mm.import_memories("team_memories.json")

7. Summary & Stats

print(mm.format_summary())

🧠 Total Active Memories: 24  |  Archived: 3
   Avg Importance: 7.4/10

📊 BY TYPE
  • correction             4
  • fact                   8
  • preference             5
  • procedure              4
  • context                3

---

Importance Scoring Guide

---

API Reference

PersistentMind(storage_path, project, session_id, auto_cleanup_days)

Initialize. Data stored in .persistentmind/ by default.

remember(content, memory_type, scope, tags, importance, project, expires_in_days, source)

Store a new memory. Returns Memory object.

recall(query, scope_filter, type_filter, project_filter, limit, min_importance)

Search memories. Returns List[MemorySearchResult] sorted by relevance.

recall_by_type(memory_type, limit)

Get all memories of a specific type, sorted by importance.

recall_by_tag(tag, limit)

Get all memories with a specific tag.

get_context(project, max_tokens_estimate)

Get formatted context block for prompt injection. Corrections surfaced first.

update_memory(memory_id, content, importance, tags)

Update an existing memory's fields.

forget(memory_id, permanent)

Archive (default) or permanently delete a memory.

consolidate(dry_run)

Find near-duplicate memories. Set dry_run=False to merge them.

get_stats()

Return memory statistics dictionary.

format_summary()

Human-readable memory summary.

export_memories(output_file, include_archived)

Export to JSON for backup or team sharing.

import_memories(input_file, overwrite_duplicates)

Import from JSON export file.

---

Privacy & Security

• ✅ Zero telemetry — No data sent anywhere
• ✅ Local-only storage — Everything in .persistentmind/ on your machine
• ✅ No API keys required — Zero credentials needed
• ✅ No authentication — No accounts or logins
• ✅ Full transparency — MIT licensed, source code included

---

Changelog

[1.0.0] - 2026-02-16

• ✨ Initial release — PersistentMind
• ✨ 7 memory types: fact, preference, procedure, context, correction, relationship, reminder
• ✨ 3 scopes: global, project, session
• ✨ Full-text search with relevance scoring, importance boosting, recency decay
• ✨ Prompt context injection via get_context()
• ✨ Automatic tag extraction from content
• ✨ Memory consolidation for deduplication
• ✨ Export/import for team sharing
• ✨ Auto-expiry and stale session cleanup
• ✨ Zero dependencies, local-only storage, MIT licensed

---

Last Updated: February 16, 2026 Current Version: 1.0.0 Status: Active & Community-Maintained

© 2026 UnisAI Community