Skip to content


Control the behavior of episodic memory.


epmem -e|--enable|--on
epmem -d|--disable|--off
epmem -i|--init
epmem -c|--close
epmem -g|--get <parameter>
epmem -s|--set <parameter> <value>
epmem -S|--stats [<statistic>]
epmem -t|--timers [<timer>]
epmem -v|--viz <episode id>
epmem -p|--print <episode id>
epmem -b|--backup <file name>


Option Description
-e, --enable, --on Enable episodic memory.
-d, --disable, --off Disable episodic memory.
-i, --init Re-initialize episodic memory
-c, --close Disconnect from episodic memory
-g, --get Print current parameter setting
-s, --set Set parameter value
-S, --stats Print statistic summary or specific statistic
-t, --timers Print timer summary or specific statistic
-v, --viz Print episode in graphviz format
-p, --print Print episode in user-readable format
-b, --backup Creates a backup of the episodic database on disk


The epmem command is used to change all behaviors of the episodic memory module, except for watch output, which is controlled by the trace --epmem command.


Due to the large number of parameters, the epmem command uses the --get|--set <parameter> <value> convention rather than individual switches for each parameter. Running epmem without any switches displays a summary of the parameter settings.

Main Parameters

Parameter Description Possible values Default
append Controls whether database is overwritten or appended when opening or re-initializing on, off off
balance Linear weight of match cardinality (1) vs. working memory activation (0) used in calculating match score [0, 1] 1
database Database storage method file, memory memory
exclusions Toggle the exclusion of an attribute string constant any string epmem, smem
force Forces episode encoding/ignoring in the next storage phase ignore, remember, off off
learning Episodic memory enabled on, off off
merge Controls how retrievals interact with long-term identifiers in working memory none, add none
path Location of database file empty, some path empty
phase Decision cycle phase to encode new episodes and process epmem link commands output, selection output
trigger How episode encoding is triggered dc, output, none output

Performance Parameters

Parameter Description Possible values Default
cache-size Number of memory pages used in the SQLite cache 1, 2, ... 10000
graph-match Graph matching enabled on, off on
graph-match-ordering Ordering of identifiers during graph match undefined, dfs, mcv undefined
lazy-commit Delay writing semantic store changes to file until agent exits on, off on
optimization Policy for committing data to disk safety, performance performance
page-size Size of each memory page used in the SQLite cache 1k, 2k, 4k, 8k, 16k, 32k, 64k 8k
timers Timer granularity off, one, two, three off

The learning parameter turns the episodic memory module on or off. When learning is set to off, no new episodes are encoded and no commands put on the epmem link are processed. This is the same as using the enable and disable commands.

The phase parameter determines which decision cycle phase episode encoding and retrieval will be performed.

The trigger parameter controls when new episodes will be encoded. When it is set to output, new episodes will be encoded only if the agent made modifications to the output-link during that decision cycle. When set to 'dc', new episodes will be encoded every decision cycle.

The exclusions parameter can be used to prevent episodic memory from encoding parts of working memory into new episodes. The value of exclusions is a list of string constants. During encoding, episodic memory will walk working memory starting from the top state identifier. If it encounters a WME whose attribute is a member of the exclusions list, episodic memory will ignore that WME and abort walking the children of that WME, and they will not be included in the encoded episode. Note that if the children of the excluded WME can be reached from top state via an alternative non-excluded path, they will still be included in the encoded episode. The exclusions parameter behaves differently from other parameters in that issuing epmem --set exclusions <val> does not set its value to <val>. Instead, it will toggle the membership of <val> in the exclusions list.

The path parameter specifies the file system path the database is stored in. When path is set to a valid file system path and database mode is set to file, then the SQLite database is written to that path.

The append parameter will determine whether all existing episodes recorded in a database on disk will be erased when epmem loads it. Note that this affects episodic memory re-initialization also, i.e. if the append setting is off, all episodic memories stored to disk will be lost when an init-soar is performed. Note that episodic memory cannot currently append to an in-memory database. If you perform an init-soar while using an in-memory database, all current episodes stored will be cleared.

Note that changes to database, path and append will not have an effect until the database is used after an initialization. This happens either shortly after launch (on first use) or after a database initialization command is issued. To switch databases or database storage types after running, set your new parameters and then perform an epmem --init.

The epmem --backup command can be used to make a copy of the current state of the database, whether in memory or on disk. This command will commit all outstanding changes before initiating the copy.

When the database is stored to disk, the lazy-commit and optimization parameters control how often cached database changes are written to disk. These parameters trade off safety in the case of a program crash with database performance. When optimization is set to performance, the agent will have an exclusive lock on the database, meaning it cannot be opened concurrently by another SQLite process such as SQLiteMan. The lock can be relinquished by setting the database to memory or another database and issuing init-soar/epmem --init or by shutting down the Soar kernel.

The balance parameter sets the linear weight of match cardinality vs. cue activation. As a performance optimization, when the value is 1 (default), activation is not computed. If this value is not 1 (even close, such as 0.99), and working memory activation is enabled, this value will be computed for each leaf WME, which may incur a noticeable cost, depending upon the overall complexity of the retrieval.

The graph-match-ordering parameter sets the heuristic by which identifiers are ordered during graph match (assuming graph-match is on). The default, undefined, does not enforce any order and may be sufficient for small cues. For more complex cues, there will be a one-time sorting cost, during each retrieval, if the parameter value is changed. The currently available heuristics are depth-first search (dfs) and most-constrained variable (mcv). It is advised that you attempt these heuristics to improve performance if the query_graph_match timer reveals that graph matching is dominating retrieval time.

The merge parameter controls how the augmentations of retrieved long-term identifiers (LTIs) interact with an existing LTI in working memory. If the LTI is not in working memory or has no augmentations in working memory, this parameter has no effect. If the augmentation is in working memory and has augmentations, by default (none), episodic memory will not augment the LTI. If the parameter is set to add then any augmentations that augmented the LTI in a retrieved episode are added to working memory.


Episodic memory tracks statistics over the lifetime of the agent. These can be accessed using epmem --stats <statistic>. Running epmem --stats without a statistic will list the values of all statistics. Unlike timers, statistics will always be updated. Available statistics are:

Name Label Description
time Time Current episode ID
db-lib-version SQLite Version SQLite library version
mem-usage Memory Usage Current SQLite memory usage in bytes
mem-high Memory Highwater High SQLite memory usage watermark in bytes
queries Queries Number of times the query command has been processed
nexts Nexts Number of times the next command has been processed
prevs Prevs Number of times the previous command has been processed
ncb-wmes Last Retrieval WMEs Number of WMEs added to working memory in last reconstruction
qry-pos Last Query Positive Number of leaf WMEs in the query cue of last cue-based retrieval
qry-neg Last Query Negative Number of leaf WMEs in the neg-query cue of the last cue-based retrieval
qry-ret Last Query Retrieved Episode ID of last retrieval
qry-card Last Query Cardinality Match cardinality of last cue-based retrieval
qry-lits Last Query Literals Number of literals in the DNF graph of last cue-based retrieval


Episodic memory also has a set of internal timers that record the durations of certain operations. Because fine-grained timing can incur runtime costs, episodic memory timers are off by default. Timers of different levels of detail can be turned on by issuing epmem --set timers <level>, where the levels can be off, one, two, or three, three being most detailed and resulting in all timers being turned on. Note that none of the episodic memory statistics nor timing information is reported by the stats command.

All timer values are reported in seconds.

Level one

Timer Description
_total Total epmem operations

Level two

Timer Description
epmem_api Agent command validation
epmem_hash Hashing symbols
epmem_init Episodic store initialization
epmem_ncb_retrieval Episode reconstruction
epmem_next Determining next episode
epmem_prev Determining previous episode
epmem_query Cue-based query
epmem_storage Encoding new episodes
epmem_trigger Deciding whether new episodes should be encoded
epmem_wm_phase Converting preference assertions to working memory changes

Level three

Timer Description
ncb_edge Collecting edges during reconstruction
ncb_edge_rit Collecting edges from relational interval tree
ncb_node Collecting nodes during reconstruction
ncb_node_rit Collecting nodes from relational interval tree
query_cleanup Deleting dynamic data structures
query_dnf Building the first level of the DNF
query_graph_match Graph match
query_result Putting the episode in working memory
query_sql_edge SQL query for an edge
query_sql_end_ep SQL query for the end of the range of an edge
query_sql_end_now SQL query for the end of the now of an edge
query_sql_end_point SQL query for the end of the point of an edge
query_sql_start_ep SQL query for the start of the range of an edge
query_sql_start_now SQL query for the start of the now of an edge
query_sql_start_point SQL query for the start of the point of an edge
query_walk Walking the intervals
query_walk_edge Expanding edges while walking the intervals
query_walk_interval Updating satisfaction while walking the intervals


When debugging agents using episodic memory it is often useful to inspect the contents of individual episodes. Running epmem --viz <episode id> will output the contents of an episode in graphviz format. For more information on this format and visualization tools, see The epmem --print option has the same syntax, but outputs text that is similar to using the print command to get the substructure of an identifier in working memory, which is possibly more useful for interactive debugging.

See Also