Skip to content

feat: Memory system enhancements - dedup, TTL, context window, passport - #1

Merged
dbehnke merged 8 commits into
mainfrom
feature/guidance
Mar 11, 2026
Merged

dbehnke merged 8 commits into
mainfrom
feature/guidance

Conversation

@dbehnke

@dbehnke dbehnke commented Mar 7, 2026 •

Copy link
Copy Markdown
Owner

Summary

This PR implements complete Phase 3 memory system enhancements and observability infrastructure.

Core Features

Memory System Enhancements

  • Content Hash Deduplication - SHA-256 based server-side deduplication with unique constraint
  • TTL Support - Time-to-live for temporary memories with automatic expiration
  • Client-side Deduplication - parameter (0.95 exact, 0.85 semantic)
  • Session Auto-TTL - namespaces automatically expire after 24h

Advanced Retrieval

  • Context Window Ranking - Weighted scoring (50% relevance + 30% recency + 20% type boost)
  • Context Passport - Cross-system context transfer for Linear/GitHub/agent handoff

Observability

  • Structured Logging - JSON-formatted logs with configurable levels (debug/info/warn/error)
  • Prometheus Metrics - endpoint with HTTP, DB, and MCP operation metrics
  • Request Tracing - Automatic request ID generation via X-Request-ID header

Documentation

  • OpenAPI 3.0 Spec - Complete REST API documentation ()
  • 6 Architecture Decision Records - Documenting key architectural decisions
  • Contributing Guide - with development setup and conventions
  • Changelog - tracking all changes
  • Updated Docs - AGENT.md, README.md, docs/cli.md, docs/api.md

Changes

Database Schema v2

  • Added column (SHA-256)
  • Added and columns
  • New indexes for deduplication and expiration

MCP Tools

  • : Added and parameters
  • : Automatically filters expired memories

API Changes

  • New endpoint for Prometheus scraping
  • Request IDs automatically added to all requests

Testing

All memory package tests pass (27+ tests)
Build verified: passes

Commits

  • feat: add content hash deduplication and TTL support
  • feat: filter expired memories from recall results
  • feat: add deduplication and TTL params to remember tool
  • feat: add context window ranking and passport pattern
  • docs: update documentation for memory system enhancements
  • feat: add observability and documentation infrastructure

dbehnke and others added 8 commits March 7, 2026 14:48
- Add content_hash column (SHA-256) for server-side dedup

- Add ttl_seconds and expires_at columns for memory lifecycle

- Implement CreateWithParams for dedup and TTL options

- Add DeleteExpired() for cleanup of expired memories

- Update schema migration to v2

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
- Automatically exclude memories where expires_at < NOW()

- Ensures expired session data doesn't appear in search results

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
- Add skip_duplicate_threshold parameter (0.95 exact, 0.85 semantic)

- Add ttl_seconds parameter for temporary memories

- Session namespaces auto-default to 24h TTL

- Return existing memory when duplicate detected

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
- BuildContextWindow(): weighted scoring for LLM context optimization

  - Relevance (50%) + Recency (30%) + Type boost (20%)

  - Token budget management

- CreatePassport(): export context for cross-system handoff

- ImportPassport(): import context to target system

- Comprehensive tests for both features

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
- Update AGENT.md with new schema, Phase 3 completions, advanced features

- Update README.md with new features overview and examples

- Update docs/cli.md with new environment variables and parameters

- Add comprehensive docs/api.md with API reference

- Update CLAUDE.md with architectural facts

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
- Add observability package with structured logging, Prometheus metrics, request tracing

- Add /metrics endpoint for Prometheus scraping

- Add RequestID and Logging middleware to web server

- Create OpenAPI 3.0 specification (docs/openapi.yaml)

- Create 6 Architecture Decision Records (docs/adr/)

- Create CONTRIBUTING.md guide

- Create CHANGELOG.md

- Update AGENT.md, README.md, docs/cli.md with new features

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
The importWithEmbedding function was missing content_hash in the INSERT
statement, causing NULL values in the database. This broke the List
function which expects content_hash to be non-NULL.

- Added content_hash computation using computeContentHash()
- Added content_hash column to INSERT statement
- Added content_hash to ON CONFLICT UPDATE clause

Fixes integration test failure: TestStore_Import_Integration
@dbehnke
dbehnke merged commit fd14db8 into main Mar 11, 2026
3 checks passed
@dbehnke
dbehnke deleted the feature/guidance branch March 11, 2026 02:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant