Reported issues for Subconscious

Pod holds 12 of 12 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to Subconscious.

Most discussed

Add purge_expired(): expired entries are never deleted

TTL works as filter-at-read: expired entries stop matching but stay in ChromaDB forever. docs/architecture.md admits "storage grows monotonically until a future purge_expired() is added."

Proposed: Memory.purge_expired() deleting all entries with 0 < expires_at <= now, returning {"purged": n}. Decide and justify whether to expose it as a seventh MCP tool or keep it library-side (lean: expose it; agents that set TTLs should be able to clean up).

Acceptance:

Unit tests (can be fast-lan

Read the thread · 2026-06-11 · open · 1 comment

Tag filtering in recall and echo

remember(task, answer, tags=["work"]) stores tags today (memory.py writes tags_json metadata) and recall/echo return them, but nothing can filter by them. The docstring in tools.py has promised "future filtering" since v0.1.0. Time to deliver.

Proposed: recall(task, threshold, top_k, tags=None) and echo(task, top_k, tags=None) where tags means "candidate must carry at least one of these".

Design note: tags are stored as a JSON string in ChromaDB metadata, and Chroma where f

Read the thread · 2026-06-11 · closed · 1 comment

Share one model instance across the test suite (5 min suite to under 1 min)

The full suite takes about 5 minutes because every test builds a fresh Memory via the memory fixture (tests/conftest.py), and each Memory lazily loads sentence-transformers (about 5s per load, about 20 embedding tests).

The model is stateless across tests; only the ChromaDB collection needs to be fresh. Ideas (pick one, or propose better):

Session-scoped encoder fixture injected into per-test Memory instances
Module-level encoder cache keyed by model name inside Memory (also spe

Read the thread · 2026-06-11 · open · 1 comment

Add a type checker (pyright) to CI

The codebase is fully type-hinted but nothing enforces it; a wrong annotation would ship silently. Add pyright (basic mode) to the dev extras and the CI lint job.

Acceptance:

pyright src/ passes locally and in CI
Any genuine type errors it surfaces are fixed in the same PR (expect a handful of ChromaDB Any-typed returns to need narrowing or targeted ignores)
CONTRIBUTING.md style section mentions it

Read the thread · 2026-06-11 · open · 0 comments

Optional max_entries cap with eviction policy

The ChromaDB collection grows without bound: TTL expiry is filter-at-read (see the purge_expired issue) and nothing limits total entries. For a long-running agent this means unbounded disk growth and, at large scale, growing HNSW index memory.

Proposed: a max_entries config key (default null, meaning unlimited, preserving current behaviour). When a remember() would exceed the cap, evict. Eviction policy is the design question:

LRU by last-hit time (needs per-entry hit tracking; the echo log

Read the thread · 2026-06-11 · open · 0 comments

Benchmark harness: subconscious-mcp vs mem0, Letta, Zep, plain ChromaDB

The validation study measured this project against itself (hit rate, accuracy, token savings at two thresholds, 150 paraphrased tasks). Nothing compares it against the alternatives people actually evaluate: mem0, Letta, Zep, LangChain memory, or a hand-rolled ChromaDB loop.

Deliverable: an open harness (this repo or a sibling) that runs an identical paraphrase workload through each backend and reports hit rate, retrieval accuracy, latency, and setup friction (LOC + external services needed). Th

Read the thread · 2026-06-11 · open · 0 comments

Observability dashboard for the echo log

Every recall appends one JSONL line to <storage_dir>/echo_log.jsonl (query, nearest entry id, similarity, hit, threshold, ts). All the raw material for "is my memory paying off?" exists; nothing visualizes it.

Deliverable: a dashboard fed only by the echo log and stats(). Either a TUI (rich/textual) or a tiny local web page (no external services). Show at minimum: hit rate over time, similarity distribution of hits vs misses, drift candidates (reuse drift_report), entry count growth.

Thi

Read the thread · 2026-06-11 · open · 0 comments

Namespaces: per-project memory isolation

One global collection means a coding agent's memories from project A surface in project B. Workaround today is per-project SUBCONSCIOUS_STORAGE_DIR, which works but is invisible and easy to forget.

Proposed: a namespace config key (env SUBCONSCIOUS_NAMESPACE, default "default") mapping to a ChromaDB collection name. All six tools operate within the configured namespace. Echo log lives per-namespace.

Open question: should tools accept an optional per-call namespace argument, or is con

Read the thread · 2026-06-11 · closed · 0 comments

Most recent

Streamable HTTP transport

stdio only today. FastMCP supports streamable HTTP; exposing it makes the server usable from remote MCP clients and shared dev-team setups.

Proposed: subconscious-mcp --transport http --host 127.0.0.1 --port 8473 (default remains stdio; default host loopback only).

Scope notes:

Local-first stays the default story; HTTP mode is opt-in
No auth in v1 of this feature; bind loopback and say so loudly in docs. A token header can be a follow-up
--print-config should report the transport

Read the thread · 2026-06-11 · open · 0 comments

Multi-answer per cluster: the first-fill drift mitigation

Background: the validation study (validation/results.md) surfaced first-fill semantic drift, and v0.2.0 ships detection (drift_report). This issue is the next step: mitigation by storage design.

Idea: instead of one answer per entry, allow a cluster to hold multiple (task_text, answer) variants. At recall time, pick the variant whose task_text is most similar to the query (a second, cheap nearest-neighbour comparison within the cluster), not just the cluster centroid's answer.

Open questio

Read the thread · 2026-06-11 · open · 0 comments

Claude Code hooks: ambient memory (auto-recall on session start, auto-remember on stop)

Today an agent only benefits from memory if it chooses to call recall. Mostly it will not. Claude Code hooks can make memory ambient:

SessionStart hook: recall against the session's opening context, inject any strong hit as context
Stop hook: distill what the session accomplished into one or more remember calls
Optionally PreToolUse on expensive tools: echo first, surface "you have done something similar"

Deliverable shape: a hooks/ directory with the hook scripts plus a README sec

Read the thread · 2026-06-11 · open · 0 comments

serverInfo.version reports the FastMCP framework version, not ours

When an MCP client calls initialize, the response says "serverInfo": {"name": "subconscious-mcp", "version": "1.27.1"}. That 1.27.1 is the FastMCP framework version. Our package version (0.2.0) is what clients should see.

Cause: src/subconscious_mcp/server.py line 33 constructs FastMCP("subconscious-mcp") without passing a version. We already import __version__ in that file for the CLI flag.

Acceptance:

initialize over real stdio reports the package version (check with `examples/

Read the thread · 2026-06-11 · closed · 0 comments

The remaining reports are on the project's issue tracker.