memory-systems（记忆系统）

Memory Systems Skill

Overview

This skill addresses agent persistence across sessions through layered architectures balancing immediate context with long-term knowledge retention. Effective memory systems enable agents to learn, maintain consistency, and reason over accumulated knowledge.

Quick Start

1. Identify needs - What must persist? (entities, decisions, patterns)
2. Choose architecture - File-based, vector, graph, or hybrid
3. Design retrieval - How will memory be accessed?
4. Implement storage - With temporal validity
5. Monitor growth - Prune and consolidate regularly

When to Use

• Building cross-session agents
• Maintaining entity consistency
• Implementing reasoning over accumulated knowledge
• Designing learning systems
• Creating growing knowledge bases
• Building temporal-aware state tracking

Memory Spectrum

Memory ranges from volatile to permanent:

Effective systems layer multiple types:

• Working memory - Current context window
• Short-term - Session facts, active tasks
• Long-term - Learned patterns, entity knowledge
• Entity-specific - Per-entity history
• Temporal graphs - Time-aware relationships

Architecture Options

1. File-System-as-Memory

Structure:

memory/
├── entities/
│   └── {entity_id}.json
├── sessions/
│   └── {session_id}/
├── knowledge/
│   └── {topic}.md
└── index.json

Pros: Simple, debuggable, version-controlled Cons: No semantic search, manual organization

Implementation:

class FileMemory:
    def __init__(self, base_path: str):
        self.base = Path(base_path)

    def store(self, key: str, value: dict, category: str = "general"):
        path = self.base / category / f"{key}.json"
        path.parent.mkdir(parents=True, exist_ok=True)
        value["_stored_at"] = datetime.utcnow().isoformat()
        path.write_text(json.dumps(value, indent=2))

    def retrieve(self, key: str, category: str = "general") -> Optional[dict]:
        path = self.base / category / f"{key}.json"
        if path.exists():
            return json.loads(path.read_text())
        return None

2. Vector RAG with Metadata

Structure:

class MemoryEntry:
    id: str
    content: str
    embedding: List[float]
    metadata: dict  # entity_tags, temporal_validity, confidence
    created_at: datetime
    valid_until: Optional[datetime]

Pros: Semantic search, scalable Cons: Loses relationship information, no temporal queries

Enhancement with metadata:

def search_with_temporal_filter(
    query: str,
    as_of: datetime = None,
    entity_filter: List[str] = None
) -> List[MemoryEntry]:
    results = vector_search(query)
    return [r for r in results
            if r.is_valid_at(as_of or datetime.utcnow())
            and (not entity_filter or r.has_entity(entity_filter))]

3. Knowledge Graph

Structure:

Entities: [Person, Project, Decision, Event]
Relations: [owns, participates_in, decided_by, happened_at]

Pros: Preserves relationships, relational queries Cons: Complex setup, query language learning curve

Key capability:

MATCH (p:Person)-[:PARTICIPATES_IN]->(proj:Project)
      -[:HAS_DECISION]->(d:Decision)
WHERE d.date > $since
RETURN p.name, d.description, d.date

4. Temporal Knowledge Graph

Structure:

class TemporalFact:
    subject: str
    predicate: str
    object: str
    valid_from: datetime
    valid_until: Optional[datetime]
    source: str
    confidence: float

Pros: Time-travel queries, fact evolution tracking Cons: Most complex, highest overhead

Capability example:

# What was the project status on date X?
facts = temporal_graph.query_as_of(
    subject="project-alpha",
    predicate="has_status",
    as_of=datetime(2025, 6, 15)
)

Performance Benchmarks

Vector Store Limitations

Problems:

• "Vector stores lose relationship information"
• Cannot answer queries traversing relationships
• Lack temporal mechanisms for current vs. outdated facts

Example failure:

Query: "Who approved the decision that affected Project X?"
Vector RAG: Returns documents mentioning approvals and Project X
            but cannot connect the relationship chain

Solution: Combine vector search with graph traversal:

def hybrid_query(query: str):
    # Semantic search for relevant entities
    entities = vector_search(query)

    # Graph traversal for relationships
    for entity in entities:
        related = graph.traverse(entity.id, max_depth=2)
        entity.relationships = related

    return entities

Memory Lifecycle

Writing

def store_memory(
    content: str,
    category: str,
    entities: List[str],
    valid_from: datetime = None,
    valid_until: datetime = None,
    confidence: float = 1.0
):
    entry = MemoryEntry(
        id=generate_id(),
        content=content,
        embedding=embed(content),
        metadata={
            "category": category,
            "entities": entities,
            "confidence": confidence
        },
        valid_from=valid_from or datetime.utcnow(),
        valid_until=valid_until
    )
    storage.save(entry)

Reading

def recall_memory(
    query: str,
    context: dict,
    as_of: datetime = None,
    limit: int = 10
) -> List[MemoryEntry]:
    # 1. Semantic search
    candidates = vector_search(query, limit=limit * 3)

    # 2. Temporal filtering
    valid = [c for c in candidates if c.is_valid_at(as_of)]

    # 3. Context relevance scoring
    scored = [(c, relevance_score(c, context)) for c in valid]

    # 4. Return top results
    return sorted(scored, key=lambda x: x[1], reverse=True)[:limit]

Consolidation

def consolidate_memories(category: str, older_than_days: int = 30):
    """Combine related old memories into summaries."""
    old_memories = get_memories(
        category=category,
        before=datetime.utcnow() - timedelta(days=older_than_days)
    )

    # Group by entity
    grouped = group_by_entity(old_memories)

    for entity, memories in grouped.items():
        if len(memories) > threshold:
            summary = generate_summary(memories)
            store_memory(summary, category="consolidated", entities=[entity])
            archive_memories(memories)

Best Practices

Do

1. Match architecture to query requirements
2. Implement progressive disclosure for memory access
3. Use temporal validity to prevent outdated info conflicts
4. Consolidate periodically to manage growth
5. Design graceful retrieval failures
6. Monitor storage size and query performance

Don't

1. Store everything (be selective)
2. Ignore temporal validity
3. Mix fact types without categorization
4. Skip consolidation indefinitely
5. Trust old memories without verification
6. Ignore retrieval latency in design

Error Handling

Metrics

Related Skills

• multi-agent-patterns - Agent coordination
• context-management - Context optimization
• session-memory - Session persistence

Version History

• 1.0.0 (2026-01-19): Initial release adapted from Agent-Skills-for-Context-Engineering