foresight

ForeSight

English | 中文

A temporal-aspect long-term memory plugin for DeepSeek Harness (dsh).

Every memory carries explicit temporal semantics — a linguistic aspect (进行体 / 完成体 / 未然体 / 恒常体) paired with an anchor (time point / interval / open / none). The framework executes lifecycle mechanically: decay on anchor expiry, TTL fallback, renewal nudge, prospective review, prediction verification, and conflict resolution by evidence with a single conservative/aggressive knob (β).

The problem

Long-term memory is a data-management problem, not a prompt-engineering one. Left unmanaged, agent memories tend to hit two familiar failure modes:

Stale injection. A project that ended a month ago still competes for the injection budget as if it were current context.

Lost valid time. "I did that yesterday" comes back as "just now" — nothing records when a memory is true, let alone when it stops being true.

Why it exists

Unlike chat vendors' rolling memories, ForeSight treats memory as scheduled first-class data: every implemented tunable — expiry/TTL, renewal cadence, activation β, retrieval factor weights, injection budgets — is read from one structured policy file (policy.yaml). Fields that are not yet wired are explicitly registered as reserved in eval/DECISIONS.md §13 (no silent decoration).

ForeSight approaches this with two axes borrowed from linguistics:

In plain terms, 体 says what stage a fact is at — 进行体: "I am writing the report" (ongoing, ends someday → expires); 完成体: "the report is submitted" (concluded, permanent); 未然体: "due next week" (pending, gets verified later); 恒常体: "I drink coffee daily" (timeless — such facts belong in your SOUL.md/user.md profile, not the memory store). 锚 says when it is true — a point ("Aug 20"), an interval ("during my third year"), open ("since March"), or none (timeless).

A few design choices worth noting:

• The aspect taxonomy draws on established linguistic notions, but it is a deliberately minimal starting point rather than a complete theory — the schema is configurable (policy.yaml) and expected to evolve with use.
• The core is agent-agnostic: dsh is one adapter (platforms/dsh). Embedding and LLM services are pluggable interfaces — the default is local Ollama, and rules-based fallbacks keep the lifecycle running without a model at all.
• The lifecycle is executed by mechanism, not by model judgment: expiry, injection eligibility and conflict resolution are driven by policy; the optional LLM is used for classification/derivation only. However, this is an early exploratory implementation — the taxonomy, the policy model and the mechanics are all under active revision.

Requirements

• Node.js ≥ 20
• DeepSeek Harness (dsh) with the cordis plugin system
• An embedding backend (default: Ollama with nomic-embed-text-v2-moe, 768-dim)
• (Optional) An LLM API for classification/derivation (default: DeepSeek compatible API; rules-based fallbacks exist)

Installation (dsh profile)

# in your ~/.dsh/profiles/<name>/
pnpm add @foresight/memory

Then add the plugin to your profile's bundle list and wire it in a patch:

# cordis.patch.yml (profile-level)
- id: foresight-core
  config:
    memoryRoot: '<your data directory>'   # e.g. /home/you/.config/foresight
    dbFile: 'foresight.db'
    embedBaseUrl: 'http://localhost:11434'
    embedModel: 'nomic-embed-text-v2-moe'

Configuration — where does my data go?

Your data lives OUTSIDE the repo, in your own data directory. The plugin never ships any user data; the repository is pure code + templates.

Data directory layout

<memoryRoot>/
├── SOUL.md          # personality (copy from templates/SOUL.md.example)
├── user.md          # user profile (copy from templates/user.md.example)
├── policy.yaml      # all tunables (copy from templates/policy.yaml.example)
└── foresight.db     # SQLite store (created automatically)

On first run the plugin expects the three text files to exist. The plugin creates the directory if needed but does not silently write policy — copy the templates, then adjust:

mkdir -p ~/.config/foresight
cp templates/SOUL.md.example  ~/.config/foresight/SOUL.md
cp templates/user.md.example  ~/.config/foresight/user.md
cp templates/policy.yaml.example ~/.config/foresight/policy.yaml

Resolution chain

explicit options (adapter) → environment variables → policy.yaml → defaults

Policy file

policy.yaml is the single source of truth for the implemented tunables: permission matrix, aspect lifecycle (TTL/renewal/anchor rendering), gate categories, activation β and decay constants, retrieval factor weights (frozen: 0.40/0.20/0.25/0.15), injection budgets, nudge cadence, server port/token. Fields without an executor are explicitly listed as reserved in eval/DECISIONS.md §13. You decide your assistant's personality, profile, and memory policy — none of it is baked into the code.

Layout

src/
├── types.ts            # domain types (aspect×anchor)
├── defaults.ts         # the ONLY place default values live
├── config.ts           # resolution chain + data dir bootstrap
├── policy.ts           # policy.yaml loader + behavior lookup
├── schema.ts           # SQLite DDL + migration + sqlite-vec
├── store.ts            # CRUD, soft-delete, vectors, FTS, audit
├── gate/               # write gate: classify + validate (aspect-text)
├── govern/             # permission model
├── evolve/             # temporal expiry/TTL, activation, β conflict
├── retrieve/           # composable scoring factors + search (3 shapes)
└── store/embed.ts      # embed provider interface (Ollama default)

Verification

pnpm install
pnpm build     # tsc
pnpm test      # node --test — no external services required

All tests run against an in-memory/temp store and a fake embedder — the suite passes on a clean machine with no Ollama, no API key, and no data directory.

License

MIT